◆Error Codes Wiki

Retry-After Header — Rate Limiting and Service Unavailable Recovery

Warning4xx client error

Overview

Implement and troubleshoot the HTTP Retry-After header for handling 429 Too Many Requests and 503 Service Unavailable responses properly.

Key Details

  • The Retry-After header tells clients when they can retry a failed request
  • Used with 429 (rate limited), 503 (service unavailable), and 301 (temporary redirect) responses
  • Value can be seconds (Retry-After: 120) or an HTTP date (Retry-After: Wed, 21 Oct 2025 07:28:00 GMT)
  • Many API clients and libraries do not automatically respect Retry-After headers
  • Ignoring Retry-After can lead to client IP blocks or account suspension

Common Causes

  • Client sending requests faster than the API rate limit allows
  • Server under maintenance returning 503 with Retry-After that clients ignore
  • Bulk operations exhausting rate limit quotas quickly
  • Multiple client instances sharing the same API key and collectively exceeding limits

Steps

  1. 1Parse the Retry-After header from 429/503 responses and wait the specified duration before retrying
  2. 2Implement exponential backoff as fallback when Retry-After header is not present
  3. 3Add jitter to retry delays to prevent thundering herd when many clients retry simultaneously
  4. 4Track rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) proactively to avoid hitting limits
  5. 5Distribute requests across time windows rather than bursting to minimize 429 responses

Tags

retry-afterrate-limit429503backoff

More in 4xx Client Error

http-400-bad-requestHTTP 400 Bad Request — What It Means & How to Fix It
Error
http-401-unauthorizedHTTP 401 Unauthorized — What It Means & How to Fix It
Error
http-402-payment-requiredHTTP 402 Payment Required — What It Means & How to Fix It
Error
http-403-forbiddenHTTP 403 Forbidden — What It Means & How to Fix It
Error
http-404-not-foundHTTP 404 Not Found — What It Means & How to Fix It
Error
http-405-method-not-allowedHTTP 405 Method Not Allowed — What It Means & How to Fix It
Error

Frequently Asked Questions

Seconds (Retry-After: 60) is simpler and avoids clock synchronization issues. HTTP dates are useful when the server knows an exact recovery time (e.g., scheduled maintenance end).