On this page
HTTP retry-after semantics
The standardized HTTP header used by servers to explicitly tell clients exactly how long to wait before attempting a failed request again, preventing thundering herds.
Reference Card
- Origin/Prior Art: HTTP/1.1 Specification (RFC 2616, updated by RFC 9110).
- Related Practices: Exponential backoff, Circuit breaking, Rate limiting.
- Key Concepts:
429 Too Many Requests,503 Service Unavailable, Thundering Herd problem. - Primary Failure Modes: Clients ignoring the header entirely, Servers sending invalid date formats.
Introduction
When a server is overloaded, the worst thing a client can do is aggressively retry the exact same request every millisecond. This creates a “Thundering Herd” that ensures the server can never recover.
While clients should implement exponential backoff on their own, the server usually knows exactly when it will be ready to accept traffic again. The HTTP Retry-After header is the mechanism the server uses to communicate this explicit timeline to the client. It transforms a chaotic, uncoordinated flood of retries into a mathematically precise, server-controlled queue.
Mental Model
Think of a busy restaurant. You walk in, and there are no tables.
A bad host (a server without Retry-After) says: “We are full.” You step outside, wait five seconds, walk back in, and ask again. You do this 50 times, exhausting yourself and the host.
A good host (a server with Retry-After) says: “We are full. Come back in exactly 15 minutes.” You go for a walk, return in 15 minutes, and sit down immediately. Both sides save massive amounts of energy.
Operational Pattern
The Retry-After header is strictly defined by RFC 9110. It is primarily sent alongside two specific HTTP status codes:
503 Service Unavailable: Indicates the server is down for maintenance or temporarily overloaded.429 Too Many Requests: Indicates the client has exceeded their specific rate limit quota.
The header value can take one of two formats:
- A Delay in Seconds: A simple integer representing the number of seconds the client must wait.
HTTP/1.1 429 Too Many Requests Retry-After: 60 - An HTTP-Date: A precise timestamp indicating when the server will be ready.
HTTP/1.1 503 Service Unavailable Retry-After: Wed, 21 Oct 2026 07:28:00 GMT
Failure Modes
Rogue Clients
The primary failure mode of Retry-After is that it requires client cooperation. A server can send a beautiful, perfectly calculated Retry-After: 3600 header, but if the client’s HTTP library ignores it and retries immediately in a tight while (true) loop, the server is still under attack. Servers must enforce the Retry-After period at the network edge (e.g., blocking the client’s IP at the WAF or API Gateway if they ignore the backoff instruction).
Timestamp Parsing Errors
If a server opts to send an HTTP-Date instead of a simple integer, it must adhere perfectly to the obsolete RFC 1123 date format. If the server sends an ISO 8601 timestamp (2026-10-21T07:28:00Z), strictly compliant HTTP clients will fail to parse it, fall back to default behavior, and likely retry immediately, destroying the server. Unless you have a specific reason to use an absolute timestamp, always use the simple integer format.
Security
Be cautious when returning Retry-After alongside 503 Service Unavailable during an active DDoS attack. If you return an identical Retry-After: 60 to 100,000 malicious bots simultaneously, they will all pause, wait exactly 60 seconds, and then hit your server at the exact same millisecond. When issuing Retry-After instructions to a large volume of clients, the server should introduce slight randomization (jitter) to the value to spread out the returning traffic.
Operational Guidance
If your application provides a public API, integrating Retry-After with your Rate Limiting infrastructure is mandatory. When a user exhausts their token bucket, the API Gateway should calculate exactly when a new token will be generated and return that integer in the Retry-After header.
Provide clear documentation to your API consumers requiring them to parse and honor this header. Many modern SDK generator tools will automatically wrap HTTP clients with logic that intercepts 429 responses, sleeps the thread for the duration specified in the Retry-After header, and automatically executes the retry on behalf of the developer.