Working with the GitHub API rate limit

[wilsonwong1990]

Introduction

Building off the great discussion post around GitHub API rate limits by @devopsjester back in June 2025, I wanted to dive a bit a deeper how and methods to work within the GitHub API rate limits. @devopsjester did a great job breaking down the REST API rate limits, the GraphQL API rate limits, secondary rate limits, and overview of importance of the rate limits. To do a quick rehash:

• The GitHub API rate limits is set up to be fair, reliable, and help manage capacity.
• Make sure to back off and retry when the rate is limited
• Monitor your rate limit usage via return headers

To dive deeper into best practices of GitHub's rate limits, I wanted to provide some recommendations to consider when you build your next awesome GitHub integration.

Recommendation 1: Don't use APIs at all, use webhooks

The best advice there is when using the GitHub API is to not use if you do not have to. This may sound a bit counterintuitive in a discussion around GitHub's API, but if a webhook exists it's better to opt for that over an API call.

A lot of GitHub integrations are built on extracting data from GitHub and mainly are event driven. Imagine a GitHub integration where when a new PR opens, you want your integration to add feedback or a comment. The common thought is, let's build around the List pull requests REST API endpoint! So, you end up building an integration that looks something like this:

1. On a periodic interval, make a request to the List Pull Requests API endpoint to fetch the PRs and scan for any new ones.
2. If there is a new PR, use the Get a Pull Request API endpoint to get the information from the PR. Maybe even pull down the specific branch via git.
3. Run some check, script, etc against the PR depending on the integration you built.
4. Post a comment back into the PR with the feedback.

When you start designing, this seems to make sense: everything stays within your codebase and just naturally flows. You just feed a token into for authorization, and with a few lines of code, you will have built a working integration. Truth is, in smaller repositories where there are less frequent changes, this may work well. However, this does not scale and hence why it doesn't follow best practices: as the repository grows with more development work, there will be more PRs. And as the number of PRs grows, there are more API requests to get the specific PRs data that will consume your rate limit. Eventually, you will hit a point where you exhaust your API rate limit and your integration will break.

Webhooks on the other hand do not use the API and as it doesn't use the API, no rate limit would ever be hit. Webhooks allow you to subscribe to specific events in your organization or repository. A payload is delivered to your webhook server when the subscribed event occurs. Taking the example above, the flow would look something like this instead:

Prerequisite steps:

1. Set up a webhook server. You can use a service like smee.io or Sinatra. For more information take a look on our documentation on handling webhook deliveries.
2. Set up validation for webhook deliveries.

Steps:

1. When a new validated webhook payload regarding the repositories PR arrives, use the Get a Pull Request API endpoint to get the information from the PR.
2. Run some check, script, etc against the PR depending on the integration you built.
3. Post a comment back into the PR with the feedback.

While webhooks do add overhead by having to either set up a webhook proxy service like smee.io or a local webhook listener, this eliminates the need to poll the GitHub LIST API endpoints and allows you to write an app that focuses on just using the GitHub GET API endpoints to retrieve the needed information. Also, once a webhook service is set up, it can be used for other projects or integrations you are building that have webhook capabilities.

Recommendation 2: GitHub Apps

Whether your integration can use webhooks or not, the next recommendation is to utilize a GitHub App over a service account or
Personal Access Token. GitHub Apps are a first-class user on the GitHub platform, do not have any additional costs, and generally more secure as they have fine grained permissions. Not only that but in the context of rate limits, GitHub Apps that are owned by a GitHub Enterprise Cloud organization have a rate limit of 15,000 REST API requests per hour. This is three times the rate limit of a GitHub user! This alone can make supporting a large GitHub integration much easier and scalable.

For a detailed look at how to build a GitHub App and use the GitHub App's Installation Token for API access, please look at this community discussion post by @loujr.

Recommendation 3: Octokit as your library

Once you have considered webhooks and GitHub Apps for your GitHub integration, the next will be focusing on what libraries and SDKs you want to build on.

The recommendation is to use Octokit as it is the official SDK of GitHub. Not only that, but there are already two plugins built for
Octokit that handle rate limit logic for you: @octokit/plugin-throttling and @octokit/plugin-retry.

Most of the bugs and issues seen with adopting rate limit best practices comes with trying to hand build the logic itself. Whether it's adding sleeps or monitoring the retry-after headers, accounting for the rate limit adds on to development overhead.

Other times, developers (understandably) want to build the features for their GitHub integration first as it is more important or more exciting. This often causes rate limit logic to be push into the backlog for later work or a "nice to have".

This is where Octokit excels as it already has the two plugins that are built in to handle this logic. The @octokit/plugin-throttling tackles rate limits by queuing requests when you're approaching limits and provides callbacks for both primary and secondary rate limit events. The @octokit/plugin-retry complements @octokit/plugin-throttling by handling transient server errors. Both repositories for the plugins have excellent examples that show how easy it is to implement retries and rate limit throttling so you can focus on developing those features.

There are various third party libraries as well but do research and see if the library has rate limit logic and how it handles rate limiting.

Recommendation 4: Cache with Conditional Requests

After choosing your library and as you begin to build your code around GitHub's APIs, ETags are a great way to monitor the state of an API result if you are using the REST API. Think of ETags like a fingerprint of the resource's current state. Here's the flow:

1. First request - you get the data + an ETag header. Cache both.
2. Next request - send the cached ETag via the If-None-Match header with the request.
3. Nothing changed → GitHub returns 304 Not Modified. No body. Doesn't count against your rate limit.
4. Something changed → GitHub returns 200 OK with fresh data and a new ETag.

Here's an example of this using Octokit.js:

#!/usr/bin/env node
import { Octokit } from "octokit";
import { readFile, writeFile } from "node:fs/promises";

const OWNER = process.env.GITHUB_OWNER ?? "my-org";
const REPO = process.env.GITHUB_REPO ?? "my-repo";
const TOKEN = process.env.GITHUB_TOKEN;

const ETAG_FILE = `.etag-${OWNER}-${REPO}`;
const CACHE_FILE = `.cache-${OWNER}-${REPO}.json`;
const octokit = new Octokit(TOKEN ? { auth: TOKEN } : {});

async function readIfExists(file) {
  try {
    return await readFile(file, "utf8");
  } catch (err) {
    if (err.code === "ENOENT") return null;
    throw err;
  }
}

let response;
const cachedEtag = (await readIfExists(ETAG_FILE))?.trim();

try {
  response = await octokit.request("GET /repos/{owner}/{repo}/pulls", {
    owner: OWNER,
    repo: REPO,
    state: "open",
    per_page: 10,
    page: 1,
    headers: {
      accept: "application/vnd.github+json",
      "x-github-api-version": "2022-11-28",
      ...(cachedEtag ? { "if-none-match": cachedEtag } : {}),
    },
  });
} catch (err) {
  if (err.status === 304 || err.response?.status === 304) {
    response = { status: 304, data: null, headers: err.response?.headers ?? {} };
  } else {
    console.error(`HTTP ${err.status ?? "unknown"}`);
    process.exit(1);
  }
}

console.log(`HTTP status: ${response.status}`);

if (response.status === 304) {
  console.log("No changes — serving cached data (0 rate limit cost)");
} else if (response.status === 200) {
  if (response.headers.etag) {
    await writeFile(ETAG_FILE, `${response.headers.etag}\n`, "utf8");
  }
  await writeFile(CACHE_FILE, `${JSON.stringify(response.data, null, 2)}\n`, "utf8");
  console.log(`New data — ${response.data.length} open PRs`);
}

const cached = await readIfExists(CACHE_FILE);
if (cached === null) {
  console.log("Local cache file is missing.");
  console.log("[]");
} else {
  console.log(cached);
}

As there are no official Octokit plugins for ETags, in this example script, we are simply monitoring for 200 and 304 HTTP statuses when we make a REST API request to the List Pull Requests endpoint. On each 200 HTTP response, we record the Pull Requests data to the CACHE_FILE and the ETag value to the ETAG_FILE. On each 304 HTTP response, we instead make no changes to these files. As a 304 is a NOT MODIFIED return, it does not count against our rate limits.

While there is no plugin, by including one more header you can monitor for changes while not being billed for it.

Consider a case where you scale up this example script to monitor for new Pull Requests for 50 of your repositories every 5 minutes.

That means you would be doing the following:

• 50 repos x 12 polls/hr = 600 requests/hr

Now let's assume that 90% of the time when you make these requests, there is no change to the Pull Requests. That means 540 requests were made returning that same data, effectively meaning you wasted 540 requests.

With ETag caching, you would still do 600 requests but only 60 requests would count against your rate limit while also getting the same data.

One other consideration for conditional requests and caching is the Last-Modified header. Some endpoints will return this as a response header. Last-Modified relies on timestamps to inform of any changes since that date and time. You can then send a If-Modified-Since header for the same 304 behavior as above. Do note ETags are better still for as it monitors for actual data changes vs just a date and time, but there are situations where Last-Modified can augment the request or is a better fit due to limitations of ETags.

A couple things to consider when designing caching strategies:

1. Pagination - ETags are per-page, not per collection. If you get a 304 on say page 1 of 5, that doesn't mean pages 2-5 are unchanged. Store ETags per full page.
2. GraphQL does not support ETags. Cache GraphQL results yourself, keyed by the query and variable hash.
3. ETags are cached per token and not globally. This is very important when building around GitHub Apps as longest TTL for an installation token is 1 hour. If the token expires and you generate a new token, the ETags cached are no longer valid. In this case, you may consider to use the Last-Modified header instead.

Wrapping it all up

While on the surface rate limits seem to be a constraint and a hassle, when respected they can help make your integrations faster, more efficient, and more reliable. GitHub is a huge platform used by the smallest developers to largest companies in the world. The rate limits help maintain a fast and reliable platform for us to build on: whether it is your first python Hello World! to your massive Rust applications. When building your next GitHub integration, consider using webhooks, GitHub Apps, Octokit as your library, and Conditional Requests to help you build a reliable, efficient, and best practice following app!