Retry-After: when to try the request again
Retry-After tells a client how long to wait before repeating a request, either as a number of seconds or as an absolute date. It accompanies 503 and 429 responses.
At a glance
- Direction
- Response only.
- Defined in
- RFC 9110
- When absent
- The client chooses its own backoff, which in practice often means retrying immediately and repeatedly.
- Two formats
- A delay in seconds, or an HTTP date in GMT
- Usual statuses
- 503 Service Unavailable and 429 Too Many Requests
- Also valid on
- A 3xx, to say how long before the resource moves back
- Thundering herd
- An identical value for every client makes them all return at the same instant.
In detail
The header turns a refusal into an instruction. A 503 on its own invites a client to retry whenever it likes, which during an incident means the moment your service recovers it is hit by everything that has been failing. A number here lets you space that return out, and well behaved clients and crawlers do honour it.
Both formats are legal but they behave differently. Seconds are relative and safe against clock skew; a date is absolute and gives every waiting client the same instant to return, which is precisely the synchronised stampede you were trying to avoid. Prefer seconds, and vary the value per client if you can.
On a 429 it is the difference between a rate limit that clients can cooperate with and one they cannot. Combined with the response body naming which limit was hit, it lets a client scheduler back off intelligently instead of retrying in a tight loop and burning its remaining quota against the same wall.
Treat the value as a floor rather than a promise. A client should wait at least that long, add some randomness, and give up after a bounded number of attempts. A server should assume some clients ignore the header entirely, which is an argument for enforcing the limit rather than only advertising it.
Examples
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{"error":"rate_limited","limit":"100/minute"}HTTP/1.1 503 Service Unavailable
Retry-After: Sat, 22 Mar 2025 02:00:00 GMTEvery waiting client returns at that same instant, so add jitter on the client or prefer the seconds form.
Things that catch people out
- A single fixed value for every client produces a synchronised retry storm at the moment it expires.
- The date form is compared against the client's clock, so a device with the wrong time waits far too long or not at all.
- Cross-origin clients cannot read the header unless it is exposed, so a browser application sees a 429 with no waiting time.
Try it: HTTP Headers Checker
Check a live URL or paste headers you already have. It grades six security headers from A+ to F and lists every other header the response returned.
HTTP Headers Checker
LOCAL · Browser-OnlyView HTTP response headers for any URL
Enter any website URL to fetch and analyze its HTTP response headers. We'll automatically add https:// if needed.
Why Check Security Headers?
Security headers protect your website against common attacks like XSS, clickjacking, and MIME sniffing. They're set by your web server and cost nothing to implement. Missing security headers are one of the most common findings in security audits.
Related HTTP headers
All http headers →Location: where the client should go next
How Location works on each 3xx status, why it also appears on a 201 Created, whether relative URLs are allowed, and how to avoid an open redirect.
WWW-Authenticate: the challenge that comes with a 401
What a 401 challenge must contain, what realm means to a browser, how Bearer error codes are reported, and why a 401 without this header is malformed.
Access-Control-Expose-Headers: reading response headers
Which response headers page code can read cross-origin by default, how to expose more, and why a pagination or request id header appears empty without it.
Server: what software answered the request
What the Server header conveys, why exposing a version number helps attackers narrow their targets, and what to put there instead of removing it entirely.
Via: the proxies a message passed through
How Via records each intermediary, what the protocol and pseudonym fields mean, how it detects request loops, and why it is useful when debugging a cache.
Forwarded: the standardised proxy header
The syntax of the standard Forwarded header, how it replaces the X-Forwarded set, how to quote IPv6 addresses and ports, and how far to trust it.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL