Glossary

Retry-After

Retry-After is a response header giving either a number of seconds to wait or an HTTP-date after which to retry.

Retry-After is a response header giving either a number of seconds to wait or an HTTP-date after which to retry. It is standardised in RFC 9110, and where a server sends it, it is the most reliable scheduling information you will get from that server.

#Where it appears

It is defined for 503 responses, for 429 Too Many Requests as introduced by RFC 6585, and for 3xx responses that ask the client to come back later. Not every server sends it, and a server that does not is not misbehaving.

HTTP/1.1 503 Service Unavailable
Retry-After: 120

HTTP/1.1 429 Too Many Requests
Retry-After: Fri, 31 Dec 1999 23:59:59 GMT

#Parsing both forms

Form	Meaning	Trap
Delay in seconds	Wait that long from receipt	None. Prefer this form when you control the server
HTTP-date	Wait until that instant	Depends on clock agreement between you and the server

For the date form, compute the interval against the Date header of the same response rather than against your own clock. That removes any skew between the two machines, and skew of minutes is not unusual.

#Treat it as an instruction

The value is what the server is prepared to tolerate. Retrying sooner is not an optimisation; it is the behaviour most likely to convert a temporary limit into a lasting block, and it wastes the request as well. Where the header is absent, fall back to exponential backoff with jitter, and cap it.

Rotating to a new address in order to ignore the wait works only when the limit is applied per address. Where it is keyed to an account, a session or a credential, the new exit node changes nothing except your bandwidth bill.

Log the value you were given alongside the value you waited. A gap between the two is the first thing to check when a job that used to finish starts collecting blocks, and it is a question your own logs can answer without touching the target.

#Commonly confused with

The X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are widespread conventions with no standard defining them, no agreed units and no guarantee of presence. Read them defensively and never make your client depend on them.

Frequently asked questions

Which takes priority, Retry-After or my own backoff schedule?

Retry-After. It is the server stating what it will tolerate, and it is standardised, whereas your schedule is a guess. Wait at least as long as it asks, then apply your own backoff on top if the next attempt also fails.

How should I parse the HTTP-date form?

Compute the interval relative to the Date header in the same response rather than your local clock. That cancels any skew between the two machines. Clock differences of minutes are common enough that trusting your own time can produce a retry well before the server expects one.

Is a missing Retry-After header a server bug?

No. RFC 9110 permits the header on the relevant responses without requiring it, so plenty of correct servers omit it. Treat its absence as no information and fall back to bounded exponential backoff with jitter rather than to a fixed short retry.