Retry-After

Retry-After is the server's explicit instruction for when a retry may succeed. It accompanies 429 Too Many Requests, 503 Service Unavailable and some redirects, and holds either a number of seconds (Retry-After: 30) or an HTTP date. Honouring it is the difference between a client that recovers and one that prolongs the outage it is waiting out.

How it works

The client parses the value — both forms are valid and both occur — and schedules the retry no earlier than that. Where the header is absent, the client falls back to its own backoff policy. Good clients also cap the wait, so a misconfigured server cannot park them for a day.

The misconception

That a retry loop with a fixed one-second sleep is "handling 429". Every client doing that hits the server again in lockstep the moment the window opens. Retry-After, where present, already tells you the right number; where absent, use backoff with jitter.

Try it here

GET /coffee/v1/rush-hour allows three requests per ten seconds and answers the fourth with 429 and Retry-After; GET /protocol/v1/maintenance answers every request with 503 and Retry-After: 30.

Related

• Testing rate limiting and Retry-After
• HTTP 429 Too Many Requests

Sources

• HTTP semantics — RFC 9110
• HTTP caching — RFC 9111

Other terms

• ETag — An opaque version identifier for a representation, used to avoid re-sending it and to detect conflicting writes.
• Safe and idempotent methods — Two independent properties of HTTP methods that decide what a client is allowed to retry.
• PUT vs PATCH — PUT replaces a resource with the representation you send; PATCH applies a set of changes to it.
• Exponential backoff — A retry strategy where each wait is longer than the last, with randomness added so clients do not retry in sync.
• Request timeout — The maximum time a client will wait for a response before abandoning the request.

All glossary terms · Testing techniques · All 39 mock REST APIs

Last updated 16 October 2026