Retry-After

Rate Limiting & Quota IANA permanent response reached by regulation 3 spellings

Retry-After accompanies a 503 or a 429 and tells the caller when to come back — as seconds, or as an HTTP date. It is the most-adopted back-pressure signal in the catalog by a wide margin, which mostly reflects that it has been in the HTTP specification since 1997 while the rate-limit headers are still settling.

It also has a regulatory edge that almost nobody thinks about. Under the PSD2 RTS, a bank’s dedicated interface has to perform at least as well as its own customer channel and must not obstruct third-party providers. How you throttle, and whether you tell the caller when to return, is part of how that obligation is met or missed. A 429 with no Retry-After is indistinguishable from a wall.

The registry

Listed in the IANA HTTP Field Name Registry as a permanent entry. Defined in RFC 9110, Section 10.2.3: HTTP Semantics.

In the catalog

Declared by 229 providers across 7,691 published specification files in the API Evangelist catalog, where it appears as a response header — sent by the server.

It is spelled 3 different ways across those contracts — Retry-After, retry-after, retry-After. HTTP field names are case-insensitive (RFC 9110, §5.1), so every one of these is the same header. They are not the same string, which is why generated clients disagree about it.

Reached by regulation

No law names this header. It is evidentiary — the deployed control for an obligation that regulation does impose. It is observable at the edge: an unauthenticated request is enough to see whether a provider sends it.

Using it

Always send it with a 429 or a 503. Prefer delta-seconds over a date — clock skew is real and an agent computing a wait from a date will get it wrong. Make the value truthful: a fixed Retry-After: 60 that does not reflect your actual reset window trains clients to ignore it.