Retry-After

Description

The Retry-After response header indicates how long the client should wait before making a follow-up request. This header is typically used with responses that indicate a temporary inability to handle the request, such as 503 Service Unavailable or 429 Too Many Requests status codes.

The Retry-After header provides a standardized way for servers to communicate rate limiting policies, scheduled maintenance windows, or temporary service unavailability to clients. By explicitly telling clients when to retry, servers can manage traffic more effectively during high-load situations or planned downtime.

This header is particularly valuable for API rate limiting, as it allows servers to inform clients exactly when they can resume making requests after hitting a rate limit, rather than forcing clients to implement arbitrary backoff strategies.

Syntax

The Retry-After header can specify the delay in one of two formats:

As a number of seconds:
```
Retry-After: <seconds>
```
As an HTTP-date after which to retry:
```
Retry-After: <http-date>
```
<seconds>: A non-negative integer representing the number of seconds to wait.
<http-date>: A date and time in the HTTP date format (same format as the Date header).

Example Syntax

Retry-After: 120

This example tells the client to retry after 120 seconds.

Retry-After: Wed, 04 Jun 2025 11:00:00 GMT

This example tells the client to retry after 11:00:00 GMT on June 4, 2025.

Examples

Rate Limiting Example

A response indicating that a rate limit has been exceeded:

HTTP/1.1 429 Too Many Requests
Date: Mon, 02 Jun 2025 17:00:00 GMT
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717416000
Content-Length: 179

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit of 100 requests per hour",
  "retry_after_seconds": 60
}

In this example, the server indicates that the client should wait 60 seconds before making another request, and provides additional rate limit information in custom headers and the response body.

Service Unavailable Example

A response during scheduled maintenance:

HTTP/1.1 503 Service Unavailable
Date: Mon, 02 Jun 2025 17:10:30 GMT
Content-Type: text/html
Retry-After: Mon, 02 Jun 2025 18:00:00 GMT
Content-Length: 345

<!DOCTYPE html>
<html>
<head><title>Service Unavailable</title></head>
<body>
  <h1>Service Temporarily Unavailable</h1>
  <p>We are currently performing scheduled maintenance. Please try again after 18:00 GMT.</p>
</body>
</html>

In this example, the server is undergoing maintenance and instructs clients to retry after a specific time.

Overloaded Server Example

A response from a server experiencing high load:

HTTP/1.1 503 Service Unavailable
Date: Mon, 02 Jun 2025 17:20:45 GMT
Content-Type: application/json
Retry-After: 30
Content-Length: 154

{
  "status": "error",
  "code": "server_overloaded",
  "message": "The server is temporarily overloaded. Please retry your request later.",
  "retry_after": 30
}

In this example, the server is experiencing high load and asks clients to retry after 30 seconds to allow it to recover.

Summary

The Retry-After response header provides a standardized mechanism for servers to communicate when clients should retry a request after encountering a temporary failure or rate limit. By explicitly specifying a delay or future time for retries, servers can efficiently manage their resources during high-traffic periods, planned maintenance, or when implementing rate limiting. This header helps create more predictable and efficient client-server interactions by eliminating guesswork about when to retry failed requests, ultimately improving the reliability and performance of web services.