feat: add RequestError support (#2465)

README.md

@@ -8,7 +8,7 @@ The `octokit` package integrates the three main Octokit libraries
 2. **App client** (GitHub App & installations, Webhooks, OAuth)
 3. **Action client** (Pre-authenticated API client for single repository)
 
-## Table of contents
+## Table of contents <!-- omit in toc -->
 
 <!-- toc -->
 
@@ -23,6 +23,7 @@ The `octokit` package integrates the three main Octokit libraries
     - [`octokit.request()`](#octokitrequest)
     - [Pagination](#pagination)
     - [Media Type previews and formats](#media-type-previews-and-formats)
+    - [Request error handling](#request-error-handling)
   - [GraphQL API queries](#graphql-api-queries)
     - [Schema previews](#schema-previews)
 - [App client](#app-client)
@@ -549,6 +550,35 @@ console.log("topics on octocat/hello-world: %j", data.topics);
 
 Learn more about [Media type formats](https://docs.github.com/en/rest/overview/media-types) and [previews](https://docs.github.com/en/enterprise-server@3.2/rest/overview/api-previews) used on GitHub Enterprise Server.
 
+#### Request error handling
+
+**Standalone module:** [`@octokit/request-error`](https://github.com/octokit/request-error.js/#readme)
+
+For request error handling, import `RequestError` and use `try...catch` statement.
+
+```typescript
+import { RequestError } from "octokit";
+```
+
+```typescript
+try {
+  // your code here that sends at least one Octokit request
+  await octokit.request("GET /");
+} catch (error) {
+  // Octokit errors always have a `error.status` property which is the http response code nad it's instance of RequestError
+  if (error instanceof RequestError) {
+    // handle Octokit error
+    // error.message; // Oops
+    // error.status; // 500
+    // error.request; // { method, url, headers, body }
+    // error.response; // { url, status, headers, data }
+  } else {
+    // handle all other errors
+    throw error;
+  }
+}
+```
+
 ### GraphQL API queries
 
 Octokit also supports GitHub's GraphQL API directly -- you can use the same queries shown in the documentation and available in the GraphQL explorer in your calls with `octokit.graphql`.

package.json

@@ -27,7 +27,8 @@
     "@octokit/plugin-rest-endpoint-methods": "^7.1.1",
     "@octokit/plugin-retry": "^4.1.3",
     "@octokit/plugin-throttling": "^5.2.2",
-    "@octokit/types": "^9.2.2"
+    "@octokit/types": "^9.2.2",
+    "@octokit/request-error": "^v3.0.3"
   },
   "devDependencies": {
     "@octokit/tsconfig": "^2.0.0",

src/index.ts

@@ -1,2 +1,2 @@
-export { Octokit } from "./octokit";
+export { Octokit, RequestError } from "./octokit";
 export { App, OAuthApp, createNodeMiddleware } from "./app";

src/octokit.ts

@@ -6,6 +6,8 @@ import { throttling } from "@octokit/plugin-throttling";
 
 import { VERSION } from "./version";
 
+export { RequestError } from "@octokit/request-error";
+
 export const Octokit = OctokitCore.plugin(
   restEndpointMethods,
   paginateRest,

test/smoke.test.ts

@@ -1,4 +1,4 @@
-import { Octokit, App, OAuthApp } from "../src";
+import { Octokit, App, OAuthApp, RequestError } from "../src";
 
 describe("Smoke tests", () => {
   it("Octokit is a function", () => {
@@ -53,4 +53,16 @@ describe("Smoke tests", () => {
 
     expect(app.octokit.request).toBeInstanceOf(Function);
   });
+
+  it("RequestError inherits from Error", () => {
+    const error = new RequestError("test", 123, {
+      request: {
+        method: "GET",
+        url: "https://api.github.com/",
+        headers: {},
+      },
+    });
+
+    expect(error).toBeInstanceOf(RequestError);
+  });
 });

test/typescript-validate.ts

@@ -2,7 +2,7 @@
 // THIS CODE IS NOT EXECUTED. IT IS JUST FOR TYPECHECKING
 // ************************************************************
 
-import { App, OAuthApp, Octokit } from "../src";
+import { App, OAuthApp, Octokit, RequestError } from "../src";
 
 function expect<T>(what: T) {}
 
@@ -30,4 +30,14 @@ export async function OctokitTest() {
     }
   );
   expect<number>(issues[0].id);
+
+  const error = new RequestError("test", 123, {
+    request: {
+      method: "GET",
+      url: "https://api.github.com/",
+      headers: {},
+    },
+  });
+
+  expect<RequestError>(error);
 }