429 Does Not Mean Broken. It Means Slow Down.
Your code is fine. The API is fine. Now the calls come back with 429 Too Many Requests. You are calling it too fast.
What a rate limit is
Many apps share one API. So the API allows a maximum number of calls in a time window, like 60 per hour. Go over it and you get 429. Nothing is broken. It is a red light for a short time. Many APIs also send your count in the reply headers, so you can slow down before you hit the wall:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 53
X-RateLimit-Used: 7
X-RateLimit-Resource: core
X-RateLimit-Reset: 1790182186GitHub’s headers from a no-login call on 23 September 2026: 60 allowed, 7 used, 53 left. Your numbers will be different.
Do not retry right away
- If the reply has a Retry-After header, wait that long. It can be seconds or a date.
- No header? Wait 1 second, then 2, then 4. This is exponential backoff. Give up after a few tries.
- Add a small random delay, so a hundred workers do not all retry at the same moment.
- For big jobs, go slower from the start. One hour beats being blocked for a day.
Not every API uses 429. GitHub can also send 403. Read each API’s rate limit page.
Do this in 60 secondsRun curl -i https://api.github.com/users/octocat and find X-RateLimit-Remaining. Run it again and watch it drop by one.
Today’s AI angleAI agents often call tools in parallel, so they hit limits sooner. On a 429, the tool should say "safe to retry after 120 seconds", or wait by itself. Do not hand the agent a raw error.