Retry-After Header — Rate Limiting and Service Unavailable Recovery

Implement and troubleshoot the HTTP Retry-After header for handling 429 Too Many Requests and 503 Service Unavailable responses properly. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: 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. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: 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. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Parse the Retry-After header from 429/503 responses and wait the specified duration before retrying. Implement exponential backoff as fallback when Retry-After header is not present. Add jitter to retry delays to prevent thundering herd when many clients retry simultaneously. Track rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) proactively to avoid hitting limits. Distribute requests across time windows rather than bursting to minimize 429 responses. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.