GitHub API Rate Limit Errors: Fix 401, 403, 429, 502 & Timeout Issues

Understanding GitHub API Rate Limit and HTTP Error Codes

The GitHub REST API enforces several distinct rate-limiting tiers, and each tier surfaces a different HTTP status code. Conflating them leads to wasted debugging time. This guide walks through every error code in the cluster — 401, 403, 429, 502, and timeout — with concrete diagnostic commands and reproducible fixes.

HTTP 401 Unauthorized

Exact error message:

{"message": "Requires authentication", "documentation_url": "https://docs.github.com/rest"}

or

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

Root causes:

• No Authorization header present (anonymous request)
• Token has been revoked, expired (fine-grained PATs support expiration), or deleted
• Token string is malformed — common culprit is a trailing newline from echo $TOKEN vs printf $TOKEN
• Using a GitHub App JWT that has expired (JWTs are valid for 10 minutes max)

Fix — Step 1: Verify the token is present and well-formed

Always use printf or strip trailing newlines when reading tokens from environment or files:

TOKEN=$(cat ~/.github_token | tr -d '\n')
curl -s -H "Authorization: Bearer $TOKEN" https://api.github.com/user

A 200 response with your user object confirms the token is valid.

Fix — Step 2: Check token scopes

curl -sI -H "Authorization: Bearer $TOKEN" https://api.github.com/user \
  | grep -i x-oauth-scopes

The x-oauth-scopes header lists granted scopes. If it is empty, the token has no scopes — regenerate it with at least repo for private repository access.

HTTP 403 Forbidden

This is the most ambiguous code because GitHub uses 403 for two completely different problems.

Case A — Insufficient token scope or repository permission:

{"message": "Must have admin rights to Repository.", "documentation_url": "..."}

Fix: regenerate the token with appropriate scopes (admin:repo_hook, write:packages, etc.) or ask a repository admin to grant collaborator access.

Case B — Secondary rate limit (burst/concurrency):

{"message": "You have exceeded a secondary rate limit. Please wait a few minutes before you retry your request.", "documentation_url": "..."}

Secondary limits exist to prevent abusive request patterns: more than ~100 concurrent requests, more than 900 points/minute on the REST API, or more than 2000 points/minute on GraphQL. These limits are not reflected in the x-ratelimit-remaining header.

Fix — Distinguish the two 403 types programmatically:

import httpx, time, re

def github_get(url, token, retries=5):
    for attempt in range(retries):
        r = httpx.get(url, headers={"Authorization": f"Bearer {token}"})
        if r.status_code == 200:
            return r.json()
        if r.status_code == 403:
            body = r.json().get("message", "")
            if "secondary rate limit" in body.lower():
                wait = int(r.headers.get("retry-after", 60))
                print(f"Secondary rate limit hit, sleeping {wait}s")
                time.sleep(wait)
                continue
            else:
                raise PermissionError(f"Permission denied: {body}")
        r.raise_for_status()
    raise RuntimeError("Max retries exceeded")

HTTP 429 Too Many Requests (Primary Rate Limit)

Authenticated REST API requests are capped at 5,000 requests per hour per user. GitHub Apps acting as an installation receive up to 15,000 per hour per organization. Unauthenticated requests are limited to 60 per hour per IP.

Exact error message:

{"message": "API rate limit exceeded for user ID 12345.", "documentation_url": "https://docs.github.com/rest/overview/rate-limits-for-the-rest-api"}

Check remaining quota before you hit zero:

curl -sI -H "Authorization: Bearer $TOKEN" https://api.github.com/rate_limit \
  | grep x-ratelimit
# x-ratelimit-limit: 5000
# x-ratelimit-remaining: 47
# x-ratelimit-reset: 1708694400   <-- Unix timestamp

Convert the reset timestamp:

date -d @1708694400

Fix — Conditional requests with ETags to conserve quota:

For resources that rarely change (repository metadata, user profiles), cache the ETag header and send If-None-Match on subsequent requests. A 304 Not Modified response costs zero against your rate limit.

# First request — capture ETag
ETAG=$(curl -sI -H "Authorization: Bearer $TOKEN" \
  https://api.github.com/repos/octocat/hello-world \
  | grep -i etag | awk '{print $2}' | tr -d '\r')

# Subsequent request — free if unchanged
curl -si -H "Authorization: Bearer $TOKEN" \
     -H "If-None-Match: $ETAG" \
     https://api.github.com/repos/octocat/hello-world \
  | head -1
# HTTP/2 304  <-- no quota consumed

HTTP 502 Bad Gateway

{"message": "Server Error"}

or an empty response body with status 502.

502s from GitHub are almost always transient infrastructure errors, but they are also reliably triggered by:

• GraphQL queries exceeding the 5,000-node complexity limit
• REST requests that would return payloads over ~1MB (e.g., listing all events on a very active repository without pagination)
• Burst of parallel connections during a GitHub service incident

Diagnostic — Check GitHub status first:

curl -s https://www.githubstatus.com/api/v2/status.json | python3 -m json.tool | grep -A2 status

Fix — Paginate aggressively and add retry logic:

# Always paginate; never request more than 100 items per page
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.github.com/repos/OWNER/REPO/issues?per_page=100&page=1"

Connection Timeouts

Timeouts manifest as curl: (28) Operation timed out or equivalent library exceptions (requests.exceptions.ReadTimeout, net/http: request canceled).

Common causes:

• Client-side timeout set too low for large Git data (tarball/blob endpoints)
• Network path issue between CI runner and api.github.com
• GitHub API response streaming stalled (rare, retry resolves it)

Fix — Increase timeout and verify DNS:

# Test DNS resolution time
time nslookup api.github.com

# Test with explicit timeout (30s)
curl --max-time 30 -H "Authorization: Bearer $TOKEN" \
  https://api.github.com/repos/OWNER/REPO/tarball/main -o /dev/null -s -w "%{http_code}\n"

For SDK users (Python requests library):

import requests
r = requests.get(
    "https://api.github.com/repos/OWNER/REPO/contents/",
    headers={"Authorization": f"Bearer {token}"},
    timeout=(5, 30)   # (connect_timeout, read_timeout) in seconds
)

Production-Grade Retry Wrapper

For any service making sustained GitHub API calls, a unified retry layer handles all the error codes above:

import time, math, httpx

def github_request(method, url, token, **kwargs):
    headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
    for attempt in range(6):
        try:
            r = httpx.request(method, url, headers=headers, timeout=30, **kwargs)
        except httpx.TimeoutException:
            wait = 2 ** attempt
            print(f"Timeout, retry {attempt+1} in {wait}s")
            time.sleep(wait)
            continue

        if r.status_code in (200, 201, 204, 304):
            return r

        if r.status_code == 401:
            raise ValueError("GitHub token invalid or expired — rotate credentials")

        if r.status_code == 403:
            msg = r.json().get("message", "")
            if "secondary rate limit" in msg.lower():
                wait = int(r.headers.get("retry-after", 60))
            else:
                raise PermissionError(msg)
            time.sleep(wait)
            continue

        if r.status_code == 429:
            reset = int(r.headers.get("x-ratelimit-reset", time.time() + 60))
            wait = max(reset - time.time(), 1)
            print(f"Primary rate limit, sleeping until reset ({wait:.0f}s)")
            time.sleep(wait)
            continue

        if r.status_code == 502:
            wait = 2 ** attempt
            print(f"502 Bad Gateway, retry {attempt+1} in {wait}s")
            time.sleep(wait)
            continue

        r.raise_for_status()

    raise RuntimeError(f"All retries exhausted for {url}")