@octokit/plugin-retry

What is @octokit/plugin-retry?

The @octokit/plugin-retry npm package is designed to automatically retry failed requests in Octokit, which is a set of client libraries for accessing GitHub's API. This plugin is particularly useful for handling transient errors and rate limit exceedances, improving the robustness of applications that interact with GitHub's API.

What are @octokit/plugin-retry's main functionalities?

Automatic Retry on Failure

This feature automatically retries requests that fail due to server errors or rate limiting. The code sample shows how to integrate the retry plugin with Octokit and make a request that will be retried automatically in case of failure.

{
  const { Octokit } = require('@octokit/core');
  const { retry } = require('@octokit/plugin-retry');

  const MyOctokit = Octokit.plugin(retry);
  const octokit = new MyOctokit({ auth: 'personal-access-token' });

  octokit.request('GET /repos/{owner}/{repo}', {
    owner: 'octocat',
    repo: 'hello-world'
  }).catch(error => {
    console.error('Request failed:', error);
  });
}

Other packages similar to @octokit/plugin-retry

axios-retry

axios-retry is a library that adds a retry feature to axios, a popular HTTP client. Similar to @octokit/plugin-retry, it helps in handling transient network errors by retrying failed requests. However, axios-retry is generic and can be used with any axios request, whereas @octokit/plugin-retry is specifically tailored for Octokit and GitHub API interactions.

fetch-retry

fetch-retry extends the fetch API to support retries in a similar manner to @octokit/plugin-retry. It allows configuring retry count, retry delay, and retry on specific HTTP methods or status codes. Unlike @octokit/plugin-retry, which is designed for Octokit and GitHub API, fetch-retry can be used with any fetch-based requests, making it more versatile for different APIs.

README

plugin-retry.js

Retries requests for server 4xx/5xx responses except 400, 401, 403, 404, 422, and 451.

Usage

Browsers	Load @octokit/plugin-retry and @octokit/core (or core-compatible module) directly from esm.sh <script type="module"> import { Octokit } from "https://esm.sh/@octokit/core"; import { retry } from "https://esm.sh/@octokit/plugin-retry"; </script>
Node	Install with npm install @octokit/core @octokit/plugin-retry. Optionally replace @octokit/core with a core-compatible module import { Octokit } from "@octokit/core"; import { retry } from "@octokit/plugin-retry";

[!IMPORTANT] As we use conditional exports, you will need to adapt your tsconfig.json by setting "moduleResolution": "node16", "module": "node16".

See the TypeScript docs on package.json "exports".
See this helpful guide on transitioning to ESM from @sindresorhus

const MyOctokit = Octokit.plugin(retry);
const octokit = new MyOctokit({ auth: "secret123" });

// retries request up to 3 times in case of a 500 response
octokit.request("/").catch((error) => {
  if (error.request.request.retryCount) {
    console.log(
      `request failed after ${error.request.request.retryCount} retries`,
    );
  }

  console.error(error);
});

To override the default doNotRetry list:

const octokit = new MyOctokit({
  auth: "secret123",
  retry: {
    doNotRetry: [
      /* List of HTTP 4xx/5xx status codes */
    ],
  },
});

To override the number of retries:

const octokit = new MyOctokit({
  auth: "secret123",
  request: { retries: 1 },
});

You can manually ask for retries for any request by passing { request: { retries: numRetries, retryAfter: delayInSeconds }}. Note that the doNotRetry option from the constructor is ignored in this case, requests will be retried no matter their response code.

octokit
  .request("/", { request: { retries: 1, retryAfter: 1 } })
  .catch((error) => {
    if (error.request.request.retryCount) {
      console.log(
        `request failed after ${error.request.request.retryCount} retries`,
      );
    }

    console.error(error);
  });

Pass { retry: { enabled: false } } to disable this plugin.

Contributing

See CONTRIBUTING.md

License

MIT