Retry-After Header
An HTTP response header telling a client how long to wait before retrying. Used with 429 Too Many Requests, 503 Service Unavailable, and some 3xx redirects. Value is either delay-seconds or an HTTP-date.
The Retry-After header is the HTTP-native way for a server to tell a client "come back later, here is when." Defined in RFC 9110 section 10.2.3, it appears on three categories of response: rate-limit rejections (429 Too Many Requests), unavailability (503 Service Unavailable), and certain redirects (notably 301 Moved Permanently). The value takes one of two forms. As a non-negative integer it means seconds to wait — "Retry-After: 120" means hold off for two minutes. As an HTTP-date (RFC 7231 / RFC 9110 IMF-fixdate format) it names the earliest moment the client should retry — "Retry-After: Wed, 21 Oct 2026 07:28:00 GMT". Both forms are clock-skew sensitive; the integer form is easier to reason about and far more common in modern APIs. Retry-After is advisory, not enforceable. A well-behaved client honors it; a misbehaving client ignores it and keeps hammering. That is why production systems pair the header with actual rate limiting or circuit breakers at the edge rather than trusting the client. Many APIs also emit companion headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — on every response so clients can pace themselves before being told to. Common mistakes: omitting Retry-After on 429 or 503 (clients then fall back to exponential backoff with no upper bound, often amplifying the outage on recovery); returning Retry-After: 0 to mean "immediately" (it does — the spec permits zero, but it defeats the purpose); and using wall-clock HTTP-date values from a server whose clock is wrong, sending clients backward in time. Clients implementing retry logic should clamp the server's value against a sensible maximum, add small jitter to avoid thundering-herd retries when many clients were told the same number, and give up after a bounded total wait rather than blocking indefinitely.