How to read a Retry-After header
By Flavio
Read a Retry-After header as a number of seconds or an HTTP-date. See when the wait ends, including a past date, a two-digit year, and a fractional second.
Free toolThis tutorial uses the Retry-After Parser. It runs in your browser, so open it in another tab and follow along.
Retry-After is how a server tells a client to wait. You see it on 503 Service Unavailable, on 429 Too Many Requests, and on a 301 or 503 that is asking you not to hammer the same URL. The client is supposed to wait, then try again.
The header has two shapes, and they look nothing like each other. One is a number of seconds. Retry-After: 120 means wait two minutes from now. The other is a date. Retry-After: Fri, 06 Nov 2026 04:02:00 GMT means wait until that clock time. If you parse one shape and the server sent the other, you either retry immediately or you wait forever.
The Retry-After parser reads both. You give it the header value and a reference time, the moment you received the response. It tells you how many seconds to wait and the UTC time when the wait ends. The rules are RFC 9110 for the two shapes, and RFC 9110’s HTTP-date for the date form.
120 seconds
The reference time for these examples is 2026-11-06T04:00:00.000Z. That is 04:00 UTC on 6 November 2026. Paste 120.
Kind: delta-seconds
Seconds: 120
Reference: 2026-11-06T04:00:00.000Z
Wait until: 2026-11-06T04:02:00.000Z120 is a delay. The kind is delta-seconds, which is the spec’s name for a run of digits. The wait ends two minutes after the reference time, at 04:02 UTC. There is no note. A whole number of seconds is the easy case.
0 is legal. Paste 0 and the wait is 0 seconds, ending at the reference time itself.
Kind: delta-seconds
Seconds: 0
Reference: 2026-11-06T04:00:00.000Z
Wait until: 2026-11-06T04:00:00.000ZThe server is saying you may retry immediately. A negative number is not a delay. -1 fails. So does 120.5, and so does 120 seconds with the word attached. The message for all of those is: Retry-After must be a number of seconds or an HTTP-date.
The digits can be long. Past the point where the number stops being a safe integer, the page says: That delay is larger than this page can count. A delay of centuries is not a wait you should schedule. Past 200 characters the page says: The value is over 200 characters. This page stops there.
The same wait, written as a date
Paste Fri, 06 Nov 2026 04:02:00 GMT. Keep the same reference time.
Kind: http-date
Format: IMF-fixdate
Date: 2026-11-06T04:02:00.000Z
Seconds: 120
Reference: 2026-11-06T04:00:00.000Z
Wait until: 2026-11-06T04:02:00.000ZThis is the preferred form, IMF-fixdate. Weekday, comma, day, month, year, time, and GMT. The date is 04:02 UTC. The reference is 04:00 UTC. The gap is 120 seconds. Same answer as the number, written the other way.
6 November 2026 is a Friday, so the weekday matches and there is no note. The page checks the weekday. It does not trust it blindly, and it does not reject the date when the name is wrong. More on that below.
GMT is the timezone the spec writes. A numeric offset is not part of this format. The time is UTC.
A date that is already past
The classic example in the HTTP spec is Sun, 06 Nov 1994 08:49:37 GMT. Paste it against the same 2026 reference time.
Kind: http-date
Format: IMF-fixdate
Date: 1994-11-06T08:49:37.000Z
Seconds: 0
Reference: 2026-11-06T04:00:00.000Z
Wait until: 2026-11-06T04:00:00.000ZThat date is already in the past, so the wait is 0 seconds.
The date parses. 6 November 1994 was a Sunday, which you can check. The wait is 0 because you cannot wait a negative amount of time. “Wait until” stays at the reference time. A client should retry, not sleep until 1994.
This is the case that bites a clock. If your machine’s clock is ahead of the server, a perfectly good future date can look past, and you retry in a tight loop. If your clock is behind, you wait too long. The reference time is your input. The “Use this moment” button fills it from the clock in the browser. For a bug report, paste the time you actually received the response, not the time you opened the page.
The two older date formats
Servers still send the old forms. rfc850 looks like Sunday, 06-Nov-94 08:49:37 GMT.
Kind: http-date
Format: rfc850
Date: 1994-11-06T08:49:37.000Z
Seconds: 0
Reference: 2026-11-06T04:00:00.000Z
Wait until: 2026-11-06T04:00:00.000ZTwo notes:
The two-digit year was read as 1994. A year more than 50 years ahead is rolled back a century.
That date is already in the past, so the wait is 0 seconds.
The year 94 is the interesting one. The page first reads it as 2094. 2094 is more than 50 years after the reference time in 2026, so it rolls back a century, to 1994. That is the rule RFC 9110 gives for a two-digit year. A year that is still inside the 50-year window stays in the 2000s. 30 against a reference in 2026 stays 2030.
asctime looks like Sun Nov 6 08:49:37 1994. One space for days 10 through 31, two spaces for days 1 through 9. The day here is 6, space and digit.
Kind: http-date
Format: asctime
Date: 1994-11-06T08:49:37.000Z
Seconds: 0
Reference: 2026-11-06T04:00:00.000Z
Wait until: 2026-11-06T04:00:00.000ZThe past-date note appears again. There is no two-digit year in asctime, so the century note does not. The format name in the summary tells you which grammar matched. If you thought you had IMF-fixdate and the page says asctime, the server is sending the old shape and your parser needs to accept it.
A weekday that does not match
Paste Mon, 06 Nov 2026 04:02:00 GMT. The calendar date is the same Friday as before. The weekday says Monday.
Kind: http-date
Format: IMF-fixdate
Date: 2026-11-06T04:02:00.000Z
Seconds: 120
Reference: 2026-11-06T04:00:00.000Z
Wait until: 2026-11-06T04:02:00.000ZThe weekday name does not match the calendar date. The calendar date was kept.
The wait is still 120 seconds. The page does not throw the date away, and it does not “fix” the day to the following Monday. The numbers are the date. The name is checked and reported. A generator that prints the wrong weekday is common. Rejecting the header would turn a two-minute wait into a hard failure.
Half a second
Move the reference time to 2026-11-06T04:00:00.500Z, half a second later, and parse the same Fri, 06 Nov 2026 04:02:00 GMT.
Kind: http-date
Format: IMF-fixdate
Date: 2026-11-06T04:02:00.000Z
Seconds: 120
Reference: 2026-11-06T04:00:00.500Z
Wait until: 2026-11-06T04:02:00.000ZThe wait is rounded up to the next whole second.
The gap is 119.5 seconds. The page rounds up to 120. Waiting 119 seconds would retry half a second early. HTTP-dates have whole seconds, and a delay is whole seconds, so the wait this page reports is a whole number. Math.ceil is the rounding. You wait until the date, not until the second before it.
Dates that are not dates
Fri, 31 Feb 2026 00:00:00 GMT parses as a shape and then fails the calendar. That calendar date does not exist.
Fri, 06 Nov 2026 25:00:00 GMT fails the clock. That clock time is not a real time of day.
A reference time with no timezone fails before any of that. The reference time needs a timezone, like 2026-11-06T04:00:00.000Z.
2026-11-06T04:00:00 is incomplete. It might mean UTC, or the zone of the laptop, and those are not the same. The page asks you to write Z or an offset such as +01:00.
An empty value says: Paste a Retry-After value.
When you should invent the wait instead
This page reads a header the server already sent. If the server sent nothing, you do not have a Retry-After, and inventing one from this page will not help. You need a schedule of your own. The exponential backoff calculator builds that schedule: a base delay, a cap, and a jitter range, so a missing header does not become a tight loop.
The two tools meet when the server sends a delay and you also have a cap. Use the header’s seconds unless they are longer than you are willing to wait. A Retry-After of many hours on a request a person is staring at is a reason to surface an error, not a reason to sleep the tab.
The HTTP status codes page is the list of which statuses this header shows up on. The headers explainer names the header when you are looking at a full response. The HTTP response headers post has the short definition, including both shapes. The Fetch API post is the client side, where you read response.headers.get('retry-after') and then have to decide which shape you got. That return value is the string you paste here.
The value and the reference time are short, so they live in the URL. You can send someone the same wait. Nothing is uploaded.
Try the Retry-After Parser
Read a Retry-After header as a number of seconds or an HTTP-date, and see when the wait ends. Parsing stays in the browser.
Related tools
- Exponential Backoff Calculator: List the wait before each retry from a base delay, a multiplier, and a cap. Compare no jitter with full, equal, and decorrelated jitter.
- HTTP Status Codes: Search HTTP status codes 1xx–5xx with plain-English meanings and practical when-to-use notes.
- HTTP Response Headers Explainer: Paste response headers and get each one explained — plus warnings for missing security headers like HSTS and CSP.
Want me to talk about your product? You can sponsor this site.