Retry-After header
The Retry-After response header (RFC 7231) specifies how long the client should wait before making a follow-up request. It is used in 429 (Too Many Requests) and 503 (Service Unavailable) responses. The value can be either a number of seconds (Retry-After: 30) or an HTTP date (Retry-After: Fri, 01 Jan 2027 00:00:00 GMT). The seconds format is more portable for rate limiting use cases.
Why it matters in practice
Retry-After is the only standard way for servers to tell clients exactly when to retry, eliminating guesswork and preventing retry storms. Well-behaved clients that respect Retry-After will back off for the exact duration the server needs to recover. For rate limiting, Retry-After tells clients when their quota window resets, allowing them to retry immediately rather than waiting for a fixed backoff that might be too long or too short.
Common mistakes
- •Returning Retry-After with an HTTP date format for rate limiting — the seconds format is simpler and avoids timezone parsing issues.
- •Setting Retry-After to a very short duration (< 1 second) for rate limiting — this can cause clients to retry immediately, recreating the overload.
- •Not including Retry-After in 429 responses — clients without explicit retry timing will use generic backoff, which may be suboptimal.
Related Terms
HTTP 429 Too Many Requests
Standard status code for rate limiting responses.
RateLimit headers (IETF)
Standardized headers for communicating quota information.
X-RateLimit headers
Legacy de facto standard for rate limit state communication.
Exponential backoff
Retry wait times grow multiplicatively after each failure.