HTTP 429 Retry-After header handling

Short answer. Retry-After is either a number of seconds (Retry-After: 30) or an HTTP date. Parse both, wait that long, then retry once. If the header is missing, back off exponentially with jitter.

Example

function retryAfterMs(response) {
  const value = response.headers.get('retry-after')
  if (!value) return null
  const seconds = Number(value)
  if (!Number.isNaN(seconds)) return seconds * 1000
  const date = Date.parse(value)
  return Number.isNaN(date) ? null : Math.max(0, date - Date.now())
}

Details

• Some APIs send JSON fields instead (retry_after_seconds, reset); read the body too.
• 429 and 503 both use the header; 503 means the server, not your quota.
• RateLimit-* headers (IETF draft) announce limits before you hit them; prefer them when present.

Pitfalls

• Clock skew makes HTTP-date values negative; clamp to zero.
• Retrying a non-idempotent POST after 429 is safe only with an idempotency key.

Sources

• RFC 9110, Retry-After; RFC 6585 (checked 2026-09-10).