The Retry-After HTTP response header indicates how long the user agent should wait before making a follow-up request.

Syntax options

RFC 9110 specifies two valid formats for Retry-After:

An integer representing the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

2. Absolute HTTP-Date

A full HTTP-date timestamp indicating when the service will be available:

HTTP/1.1 503 Service Unavailable
Retry-After: Fri, 11 Sep 2026 10:15:00 GMT

When is Retry-After used?

  • HTTP 429 Too Many Requests: Sent by rate limiters to tell clients when their quota window resets.
  • HTTP 503 Service Unavailable: Sent during scheduled maintenance or temporary backend server overload.
  • HTTP 301 / 500 / 413: In specific custom policies where temporary constraints apply.

Client implementation with jitter

When building automated API clients, do not retry all failed requests simultaneously when the delay expires (the “thundering herd” problem). Add a randomized jitter:

const retryAfterSeconds = parseInt(response.headers.get('Retry-After') || '5', 10);
const jitterMs = Math.random() * 1000;
await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1000 + jitterMs));

Inspecting with curl

Inspect rate limit response headers with curl:

curl -i https://api.example.test/v1/rate-limited-endpoint

Key takeaway

The Retry-After header coordinates client backoff during rate limiting (429) or maintenance downtime (503). APIs should prefer integer delay-seconds and client applications should always incorporate random jitter into retry schedules.