GitHub Error: 403_rate_limit — REST API Rate Limit Exceeded

HTTP/1.1 403 Forbidden
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714150800
X-RateLimit-Resource: core

{
  "message": "API rate limit exceeded for 203.0.113.42. (But here's the good news: Authenticated requests get a higher rate limit.)",
  "documentation_url": "https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"
}

GitHub’s 403 with X-RateLimit-Remaining: 0 is the most common production blocker for any code that talks to the GitHub API. The fix is rarely “wait longer” — it’s almost always one of: authenticate, use conditional requests, switch to GraphQL, or upgrade from PAT to GitHub App. Each move multiplies your effective quota by 5-100x.

The single biggest win is conditional requests with ETags. Most GitHub data (repo metadata, branch SHAs, label lists) changes rarely. A naive integration that re-reads the same resource every minute spends 60 calls/hour per resource; the same code with If-None-Match spends maybe 3-5 because most reads return 304. That alone takes you from constant throttling to a comfortable margin.

Why this happens

• Unauthenticated requests on a CI runner. GitHub's unauthenticated quota is 60/hour per source IP. CI runners (especially shared GitHub Actions runners on shared NAT) consume this collectively. A single noisy job can lock out everyone else on the same exit IP for 59 minutes.
• PAT used for what should be a GitHub App. Personal access tokens get 5,000/hour. GitHub Apps get 15,000/hour per installation, scaling with your installation count. Heavy automation that runs through a PAT will throttle long before an equivalent GitHub App.
• Polling instead of webhooks. Many GitHub integrations poll `GET /repos/.../events` or `GET /notifications` every minute. That alone burns 60 RPH; combined with other reads, you'll hit the cap. Switch to webhooks or the events stream for change-driven updates.
• REST search API on its own tighter limit. `GET /search/...` has a separate, much lower limit (30/min authenticated, 10/min unauthenticated). Hitting search rate limits returns the same 403 with `X-RateLimit-Resource: search`.
• Secondary (abuse) rate limit. If you hammer a single endpoint with high concurrency, GitHub may return a 403 with `Retry-After` and a different message — the secondary rate limit. It's separate from the per-hour budget and triggers on burst patterns.

How to fix it

Fixes are ordered by likelihood. Start with the first one that matches your context.

import { Octokit } from "@octokit/rest";

const octokit = new Octokit({
  auth: process.env.GITHUB_TOKEN,
  // Octokit auto-handles primary rate limit and retries
  throttle: {
    onRateLimit: (retryAfter, options) => {
      console.warn(`Rate limited on ${options.method} ${options.url}, retrying in ${retryAfter}s`);
      return options.request.retryCount < 3;
    },
    onSecondaryRateLimit: (retryAfter, options) => {
      console.warn(`Secondary rate limit on ${options.method} ${options.url}`);
      return options.request.retryCount < 1;
    },
  },
});

import time, requests

def get(url, token, max_attempts=3):
    for _ in range(max_attempts):
        r = requests.get(url, headers={"Authorization": f"Bearer {token}"})
        if r.status_code != 403 or 'X-RateLimit-Remaining' not in r.headers:
            return r
        if int(r.headers['X-RateLimit-Remaining']) > 0:
            return r
        reset_at = int(r.headers['X-RateLimit-Reset'])
        sleep_for = max(0, reset_at - int(time.time())) + 5
        time.sleep(sleep_for)
    r.raise_for_status()

const cache = new Map();

async function getRepo(owner, repo) {
  const url = `https://api.github.com/repos/${owner}/${repo}`;
  const headers = {
    Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
  };
  const cached = cache.get(url);
  if (cached) headers['If-None-Match'] = cached.etag;
  const r = await fetch(url, { headers });
  if (r.status === 304) return cached.body;  // free read
  const body = await r.json();
  cache.set(url, { etag: r.headers.get('etag'), body });
  return body;
}

Detection and monitoring in production

Log `X-RateLimit-Remaining` on every response and emit it as a metric. Alarm when remaining drops below 10% of the limit for more than 5 minutes — that's an incoming 403. For GitHub Apps, expose the metric per installation so you can see which one is the heavy user.

Read more: /guide/handling-rate-limits/