devkult_
tools29converters34
home/headers/retry-after

Retry-After

response headerrouting & context

How long the client should wait before retrying — sent with 429, 503 and some redirects.

Retry-After turns 'go away' into 'come back later'. On 429 Too Many Requests it says when the rate limit resets; on 503 Service Unavailable it says when maintenance should end. Well-behaved clients wait at least that long instead of retrying on their own schedule.

Syntax

Retry-After: <seconds>   or   Retry-After: <http-date>

Defined in RFC 9110 §10.2.3 — Retry-After.

Examples

Retry-After: 120

retry in two minutes

Retry-After: Wed, 21 Oct 2026 07:28:00 GMT

retry after a specific time

Good to know

  • Clients must handle both forms: Number(value) for seconds, Date.parse(value) for dates.
  • Search engines treat a 503 with Retry-After as temporary, so planned maintenance doesn't cost rankings.
  • Add jitter on the client so everyone who was rate-limited doesn't return in the same second.

Further reading: Retries, backoff and jitter

How to set Retry-After

Express
res.set("Retry-After", "120").status(429).json({ error: "rate_limited" });
Next.js (route handler)
return Response.json(
  { error: "rate_limited" },
  { status: 429, headers: { "Retry-After": "120" } },
);
nginx (maintenance)
location / {
  add_header Retry-After 3600 always;
  return 503;
}
Client (fetch)
const header = res.headers.get("Retry-After");
const seconds = Number(header);
const waitMs = Number.isNaN(seconds)
  ? Date.parse(header) - Date.now()
  : seconds * 1000;

Check it

Fetch only the response headers and filter for Retry-After. In the browser, it's under Response Headers in DevTools → Network.

curl -sI https://example.com/ | grep -i '^retry-after:'

To compare response headers across many URLs at once, use the HTTP Status Checker.

Frequently asked questions

Can JavaScript read Retry-After on a cross-origin response?

Only if the server lists it in Access-Control-Expose-Headers, since it isn't on the CORS-safelisted response headers.

Status codes it appears with
Related headers