What is Retry-After Header?
An HTTP response header that tells clients how long to wait before retrying a failed request.
Definition
The Retry-After HTTP response header indicates how long a client should wait before making a follow-up request. It is typically sent with 429 (Too Many Requests) or 503 (Service Unavailable) responses. The value can be a number of seconds (e.g., "Retry-After: 120") or an HTTP date (e.g., "Retry-After: Fri, 31 Dec 2027 23:59:59 GMT"). Respecting this header is essential for well-behaved API clients and cron job retry logic.
Simple Analogy
Like a restaurant host saying "your table will be ready in 15 minutes" — instead of asking repeatedly, you wait the specified time before checking again.
Why It Matters
When your cron job endpoint returns a 429 or 503 with a Retry-After header, ignoring it can get your IP rate-limited or blocked. Respecting the header ensures your retries succeed and maintains good relationships with external APIs. CronJobPro honors Retry-After headers in its retry logic, scheduling retries at the specified time instead of immediately.
How to Verify
Inspect response headers from your endpoint during failures: look for "Retry-After" in 429 and 503 responses. In CronJobPro, check execution details for rate-limiting indicators. Test your endpoint under load to see if it returns Retry-After headers when overwhelmed. Verify your retry logic respects the header value.
Common Mistakes
Ignoring the Retry-After header and retrying immediately, which often makes the situation worse. Not implementing Retry-After in your own endpoints when they are overloaded. Treating Retry-After as optional when it is sent with 429 responses — violating it may result in your client being blocked entirely.
Best Practices
Always respect Retry-After headers in your retry logic. Implement Retry-After in your own endpoints to give clients clear guidance during overload. Use CronJobPro which automatically honors Retry-After headers. When building APIs, prefer seconds format over date format for simplicity and timezone safety.
HTTP Methods Guide
Learn about HTTP methods
Try it free →Frequently Asked Questions
What is Retry-After Header?
The Retry-After HTTP response header indicates how long a client should wait before making a follow-up request. It is typically sent with 429 (Too Many Requests) or 503 (Service Unavailable) responses. The value can be a number of seconds (e.g., "Retry-After: 120") or an HTTP date (e.g., "Retry-After: Fri, 31 Dec 2027 23:59:59 GMT"). Respecting this header is essential for well-behaved API clients and cron job retry logic.
Why does Retry-After Header matter for cron jobs?
When your cron job endpoint returns a 429 or 503 with a Retry-After header, ignoring it can get your IP rate-limited or blocked. Respecting the header ensures your retries succeed and maintains good relationships with external APIs. CronJobPro honors Retry-After headers in its retry logic, scheduling retries at the specified time instead of immediately.
What are best practices for Retry-After Header?
Always respect Retry-After headers in your retry logic. Implement Retry-After in your own endpoints to give clients clear guidance during overload. Use CronJobPro which automatically honors Retry-After headers. When building APIs, prefer seconds format over date format for simplicity and timezone safety.
Related Terms
Retry
Automatically re-executing a failed job to recover from transient errors.
Rate Limiting
Restricting the number of requests a client can make within a time window to prevent abuse.
HTTP Status Code
A three-digit number returned by a server indicating the result of an HTTP request.
Exponential Backoff
A retry strategy that doubles the wait time between each successive retry attempt.
Backoff with Jitter
Exponential backoff with added randomness to prevent synchronized retry storms.