[ADP-139] Retry-After

reviewing phase 1

Response content should be unified.

Overview

The Retry-After header provides guidance to the client on when to retry a request after receiving certain status codes. This ADP outlines best practices for using the Retry-After header in API design and implementation.

Guidance

• The Retry-After header SHOULD be used with appropriate status codes, such as 429 (Too Many Requests) and 503 (Service Unavailable).
• The value of Retry-After SHOULD be either an HTTP date or a delay in seconds.
• The API SHOULD provide accurate and reasonable Retry-After values to help clients manage their requests effectively.
• The Retry-After header can be used in a 301 (Moved Permanently) response to indicate when the resource will be available at its new location.

Format of Retry-After

1. HTTP date format:

   Retry-After: Fri, 31 Dec 2023 23:59:59 GMT

2. Delay in seconds:

   Retry-After: 120

Example

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Content-Language: en
Retry-After: 30
{
  "type": "https://example.com/problems/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit. Please retry after 30 seconds.",
  "retryAfter": 30
}

Related ADP

• ADP-43: API Rate Limiting

References

• MDN Web Docs: Retry-After
• RFC 9110: Retry-After