Self-Healing CI: Auto-Retrying "API rate limit exceeded"
A step failing with "API rate limit exceeded" consumed its request budget: the token is valid, the budget refills on a fixed clock, and the same call succeeds after it does.
The problem
A workflow step that calls the GitHub REST or GraphQL API fails reporting the rate limit. Authentication is working. Either the calls were unauthenticated, which carries a much smaller per-address budget shared with every other job on that address, or an authenticated budget was consumed by a job making many calls in a loop.
API rate limit exceeded for 49.37.45.101. (But here's the good news: Authenticated requests get a higher rate limit.)Why it happens
Unauthenticated requests are counted against the originating address, so on hosted CI the budget is shared with unrelated jobs and can be exhausted by traffic that is not yours.
The response carries an X-RateLimit-Reset header naming the exact moment the budget refills, which means the correct wait is knowable rather than a guess.
The manual fix
Manual mitigations for a GitHub API rate limit:
- Authenticate the call, even for public data, to move off the shared anonymous budget.
- Re-run the job after the reset window has passed.
- Batch or cache API results so a single run does not make the same call repeatedly.
curl -sS -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/rate_limitHow this gets automated
Rate limits are the clearest case for automated recovery in CI: the failure is not a defect, the wait is bounded, and the reset time is published in the response. The only reason it costs anyone time is that the job fails and a person has to notice and re-run it. A self-healing pipeline recognizes the frame, waits past the window, and retries, turning a red build into a slower green one.