What does the HTTP Retry-After response header mean, what value formats does it accept, and on which responses should an API send it?

## What the header says `Retry-After` is defined by the HTTP specification as a way for a server to tell a client how long to wait before issuing a follow-up request. It converts a bare "no" into an actionable "no, try again after N" — the difference between a client guessing and a client cooperating. ## The two formats **Delay-seconds**: a non-negative integer, relative to when the response was received. ``` Retry-After: 120 ``` **HTTP-date**: an absolute timestamp in the standard HTTP date format. ``` Retry-After: Wed, 12 Aug 2026 14:00:00 GMT ``` Both are legal, so a client must handle either. In practice **prefer delay-seconds** when generating: - It is immune to **client clock skew** — a client whose clock is minutes off will compute a nonsense wait from an absolute date, potentially zero or negative. - It requires no date parsing, historically a source of bugs. - It is trivially correct behind caches and proxies that add transit delay only in the client's favour. Absolute dates make sense when the reset is a genuinely fixed wall-clock moment, such as a scheduled maintenance window ending, and you want that stated exactly. ## Where it belongs - **429 Too Many Requests.** The natural value is the time until the client's rate-limit window resets. This is the single most useful place for the header: without it the client picks an arbitrary backoff, which is either too aggressive (it keeps getting 429s) or too conservative (it stalls unnecessarily). - **503 Service Unavailable.** The expected duration of the outage or maintenance. A short value tells a client to hold on; a long value tells it to fail the operation and requeue. - **3xx redirects.** The specification also allows it here, to ask the client to delay before following the redirect. Rare in practice. It is **meaningless on most other errors**. On a `400` or `422` the request is wrong and time changes nothing; sending a delay there invites pointless retries of a request that will never succeed. ## What it does not promise It is a *lower bound on the wait*, not a guarantee that a request at that moment will succeed. If load is still high, the next attempt may return another 429 with a new `Retry-After` — and the client must honour the new value rather than assuming the first one was final. ## The jitter problem If a server returns `Retry-After: 60` to ten thousand clients at once, all ten thousand retry within the same second. The header has synchronised them into a coordinated burst — precisely the pattern the rate limiter existed to prevent. The correct client behaviour is to treat the value as a **floor** and add randomised jitter above it. A well-behaved server can help by varying the value slightly per client. ## Server-side honesty Only send a value you can justify. An invented `Retry-After: 30` on an outage that lasts an hour produces a client retrying twice a minute for an hour — load you did not want during an incident. If the duration is unknown, either omit the header (the client falls back to its own exponential backoff) or send a deliberately conservative value. ## Client-side sanity checks A client should clamp the value. A hostile or buggy server can send `Retry-After: 86400`, and a client that blindly sleeps a day has effectively been shut down by a header. Cap it at something appropriate for the operation, and treat an unreasonably large value as "fail now and let a human or a scheduler decide". Equally, ignore malformed values rather than crashing, and never treat a missing header as permission to retry immediately.