GitHub API Rate Limit Exceeded (401, 403, 429, 502, Timeout): Complete Troubleshooting Guide

Understanding GitHub API Rate Limit Errors

GitHub enforces multiple rate limit tiers on its REST and GraphQL APIs. Understanding which limit you've hit is the critical first diagnostic step — the error code and response headers tell the full story.

Rate Limit Tiers

Primary rate limit (REST): Unauthenticated requests are capped at 60 requests per hour per originating IP. Authenticated requests (PAT, OAuth token, GitHub App) receive 5,000 requests per hour per user or installation. GitHub Apps acting on behalf of organizations can reach 15,000 requests per hour.

Secondary rate limit: GitHub imposes a concurrent request cap and a points-per-minute cap (~1,000 points/minute for mutations). You'll see a Retry-After header and HTTP 429 or occasionally 403 when this limit triggers.

GraphQL rate limit: Measured in query complexity points. Each query costs between 1–5,000 points depending on resource count. Budget is 5,000 points per hour.

Step 1: Read the Response Headers

Every GitHub API response includes rate limit headers. Always log these in your HTTP client:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708732800
X-RateLimit-Used: 5000
X-RateLimit-Resource: core
Retry-After: 3600

X-RateLimit-Reset is a Unix timestamp. Convert it to human-readable time with date -d @1708732800. Retry-After appears on secondary rate limit responses and must be honoured — do not retry before this time.

For the GraphQL API, query the rate limit endpoint directly:

query {
  rateLimit {
    limit
    cost
    remaining
    resetAt
    nodeCount
  }
}

Step 2: Identify the Specific Error

HTTP 401 — Bad credentials

Exact error body:

{"message": "Bad credentials", "documentation_url": "https://docs.github.com/rest"}

Causes: expired PAT, revoked token, incorrect Authorization header format, using a deleted GitHub App credential.

Fix: Run curl -H "Authorization: Bearer YOUR_TOKEN" https://api.github.com/user and verify the token is active in Settings → Developer settings → Personal access tokens. Ensure the header uses Bearer (not token) for fine-grained PATs.

HTTP 403 — Forbidden / Resource not accessible

Exact error body:

{"message": "Resource not accessible by integration", "documentation_url": "https://docs.github.com/rest/overview/permissions-required-for-github-apps"}

Causes: OAuth token missing required scope, GitHub App installation lacks repository permission, organization SSO not authorized for the token.

Fix: Inspect the X-OAuth-Scopes header in any API response to see granted scopes. Compare against X-Accepted-OAuth-Scopes which lists required scopes. If the token is SAML-protected, navigate to Settings → Applications → Authorized OAuth Apps and click Authorize next to your organization.

HTTP 429 — Too Many Requests (Secondary Rate Limit)

Exact error body:

{"message": "You have exceeded a secondary rate limit. Please wait a few minutes before you try again.", "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api"}

Fix: Immediately stop all requests. Read the Retry-After header value in seconds. Sleep for that exact duration before resuming. Do not parallelize write operations (POST, PUT, PATCH, DELETE) — GitHub counts concurrent mutations heavily against the secondary limit.

HTTP 502 — Bad Gateway

Causes: Oversized response payloads, GitHub infrastructure instability, network intermediaries.

Fix: Reduce per_page from 100 to 30, add request timeouts (15–30s), implement retry logic, and check https://www.githubstatus.com for active incidents.

Timeout (no HTTP response)

Causes: Very large repository operations (git clone, archive download), slow network, lack of request timeout configuration.

Fix: Set explicit connection and read timeouts in your HTTP client. For curl, use --max-time 30. For Python requests, use requests.get(url, timeout=(5, 30)) (connect timeout, read timeout).

Step 3: Apply the Correct Fix

Fix A — Add authentication

The single highest-impact change. Move from 60 to 5,000 requests/hour instantly:

export GITHUB_TOKEN=ghp_yourtoken
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
     -H "Accept: application/vnd.github+json" \
     https://api.github.com/rate_limit

Fix B — Implement conditional requests

Cache the ETag from any GET response and send If-None-Match on subsequent requests. A 304 response costs 0 against your quota:

# First request — capture ETag
ETAG=$(curl -si -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/owner/repo/branches \
  | grep -i etag | awk '{print $2}' | tr -d '\r')

# Subsequent request — returns 304 if unchanged, free of charge
curl -si -H "Authorization: Bearer $GITHUB_TOKEN" \
     -H "If-None-Match: $ETAG" \
     https://api.github.com/repos/owner/repo/branches

Fix C — Exponential backoff with jitter

For any 429, 500, or 502 response:

import time, random, requests

def github_get(url, token, max_retries=5):
    headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers, timeout=(5, 30))
        if resp.status_code == 200:
            return resp
        if resp.status_code == 429 or resp.status_code == 503:
            retry_after = int(resp.headers.get("Retry-After", 0))
            if retry_after:
                time.sleep(retry_after)
            else:
                sleep_time = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(sleep_time)
        elif resp.status_code == 403 and "rate limit" in resp.text.lower():
            reset_time = int(resp.headers.get("X-RateLimit-Reset", time.time() + 3600))
            time.sleep(max(reset_time - time.time(), 1))
        else:
            resp.raise_for_status()
    raise Exception(f"Max retries exceeded for {url}")

Fix D — Token rotation

For high-throughput automation, rotate across multiple tokens when X-RateLimit-Remaining drops below a threshold:

import itertools
TOKENS = ["ghp_token1", "ghp_token2", "ghp_token3"]
token_pool = itertools.cycle(TOKENS)

def get_healthy_token(tokens):
    import requests
    for token in tokens:
        r = requests.get("https://api.github.com/rate_limit",
                         headers={"Authorization": f"Bearer {token}"})
        data = r.json()
        if data["resources"]["core"]["remaining"] > 100:
            return token
    return None  # all tokens exhausted — wait for reset

Step 4: Verify the Fix

After applying changes, confirm your rate limit status and token validity:

curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/rate_limit | jq '.resources.core'

Expected healthy output:

{"limit": 5000, "used": 42, "remaining": 4958, "reset": 1708736400}

If remaining is 0, calculate wait time:

echo $(( $(date -d @$(curl -s -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/rate_limit | jq .resources.core.reset) +%s) - $(date +%s) )) seconds until reset