What is a Retry-After header?
Tells the client how long to wait before making a follow-up request, used with 429 and 503 responses.
Retry-After tells a client exactly how long to back off before trying again, most commonly seen with a 429 Too Many Requests when rate limiting kicks in, or a 503 Service Unavailable during planned maintenance. A well-behaved uptime monitor should respect this header rather than hammering a website that's explicitly asked for a breather, and a well-built API should send it consistently so automated clients (and monitors) can back off gracefully instead of making an outage worse.
Common use case
A rate-limited API sends Retry-After: 30 alongside a 429, letting a well-behaved client library wait exactly the right amount of time before automatically retrying instead of guessing.
Example
Retry-After: 120History
Part of the original HTTP/1.1 specification, RFC 2068 (1997).
Did you know?
It accepts two completely different value formats - either a number of seconds to wait, or a full HTTP-date to wait until - and a correct client implementation needs to handle both.