A 429 Too Many Requests response tells a client it sent too many requests in a given time. The server may include a Retry-After header saying how long to wait. Good servers send both, and good clients back off instead of retrying immediately.
What the standard says
RFC 6585 defines the 429 status code. Its text says the response may include a Retry-After header indicating how long to wait before making a new request, with an example of 3600, which is one hour in seconds. It also says responses with this status code must not be stored by a cache.
That last point is easy to miss. If a shared cache stores a 429, other users may receive someone else's rate limit error.
What servers should do
- Return 429, not a generic 500 or a silent drop, so clients know the cause.
- Include Retry-After where you can compute a sensible value.
- Keep the body small and free of internal detail. A short message is enough.
- Make sure caches do not store the response.
- Log the event with the client identity so you can tell abuse from a bug.
The limit itself is covered in the resource limits checklist. A 429 is only useful if the limit behind it is real. See also four ways a limiter allows everything.
What clients should do
Respect the wait. If Retry-After is present, wait at least that long before the next request to the same endpoint.
Back off when it is absent. Use increasing delays with some randomness, so many clients do not all retry at the same instant.
Cap retries. Give up after a small number of attempts and surface the error. Endless retries turn a limit into a traffic amplifier.
Do not retry unsafe calls blindly. A retried payment or order call can create duplicates unless the API supports idempotency keys.
Slow down proactively. If you know the documented limit, pace requests under it rather than running into the wall.
Common mistakes
- Retrying in a tight loop, which makes the limit last longer.
- Treating 429 as a failure and discarding queued work instead of delaying it.
- Rotating addresses or keys to dodge a limit. That can breach the provider's terms and gets you blocked.
- Sharing one key across many services, so one noisy job starves the others.
A note on security
Rate limit responses can leak information if they differ by account existence. A reset endpoint that returns 429 only for real accounts tells an attacker which accounts exist. Apply limits in a way that does not change the visible outcome.
Quick check
Is Retry-After required with a 429?
No. RFC 6585 says the response may include it. Clients must cope without it.
Can I cache a 429?
No. The RFC says responses with this status code must not be stored by a cache.
Safeguard does not replace your gateway limits, but its dependency scanning can flag known issues in the HTTP libraries your clients use, and the free scan at gold.safeguard.sh/scan is a quick way to check.
Sources
Last reviewed: 19 October 2026.
