Blog

The Retry-After Header Nobody Reads

September 6, 2026Xerat023 min read
Share
The Retry-After Header Nobody Reads

Rate limiting is one of those features that's simple to implement on the server and consistently mishandled on the client. A server returns 429 Too Many Requests, often with a Retry-After header telling the caller exactly how long to wait — and a huge number of clients either ignore the header entirely, retry immediately in a loop, or give up and show a generic error instead of just... waiting the specified number of seconds and trying again.

What the server is actually telling you

429 on its own just means "you've sent too many requests in some window — slow down." Retry-After is the server doing you a favor: instead of forcing you to guess a backoff interval, it tells you exactly how long to wait, either as a number of seconds or an HTTP date. A client that reads this header and waits precisely that long is being about as cooperative as it's possible to be — you're not guessing, you're following an explicit instruction from the service you're calling.

Ignoring it and retrying immediately is close to the worst possible response: it guarantees another 429, burns another unit of whatever rate-limit budget you have left, and if enough clients do this simultaneously it can turn a rate limit that was protecting the server into a self-inflicted retry storm that makes the underlying problem worse, not better.

Exponential backoff is what you use when you don't have Retry-After

Not every rate-limited or flaky response comes with an explicit "wait exactly this long" instruction. When it doesn't, the standard fallback is exponential backoff with jitter: wait a short interval, and if it fails again, double the wait (roughly), up to some cap, with a small random jitter added so that many clients retrying the same failed dependency don't all retry in lockstep and recreate the exact spike that caused the failure in the first place. Cloud providers' own architecture guidance calls this out explicitly, because "everyone retries at the same fixed interval" is a common cause of the very outages retry logic is supposed to help recover from.

The rule of thumb: if the server told you exactly when to retry, use that. If it didn't, back off exponentially with jitter rather than a fixed short interval — a fixed interval is exactly the pattern that turns one struggling server into a thundering herd of synchronized retries.

What actually needs testing here

Unit tests can check that your retry function does what it's supposed to in isolation, but confirming your real HTTP client actually respects a real 429 plus a real Retry-After value — end to end, including whatever library or wrapper sits between your code and the network — needs a dependency that can actually return that combination on demand. Waiting for a real API's real rate limiter to trip during testing is unreliable at best (you might not hit the threshold, or might trip someone else's test run in a shared environment) and disruptive at worst (some providers will flag or throttle an account that trips their limiter too often).

A mock that returns a 429 with a specific Retry-After value whenever you want it to — MockBase supports this via a route's status code and templated response headers — turns "does my client actually wait the right amount of time before retrying" from a question you hope the answer to into one you can watch happen, with a stopwatch, in a test that takes a few seconds instead of hoping to get rate-limited by accident.

X

Xerat02

Building MockBase.