The Retry-After HTTP response header tells a client when it may retry a request or how long it should wait. It makes temporary limits and unavailability more predictable for consumers. section 13.2.2 section 14.2.3
Use the indicator with the response that explains why processing cannot proceed:
- Return 429 Too Many Requests with Retry-After when a consumer exceeds its rate limit. section 13.2.2 section 13.9
- Return 503 Service Unavailable with Retry-After when planned maintenance or an unavailable dependency delays processing. section 14.2.3
- Express the retry point as an HTTP date or a duration in seconds. section 13.2.2 section 14.2.3
- Use it on successful polling responses when an estimated completion time gives the consumer a sensible next-check time, although this is uncommon. section 14.7.1
Rate-limited transfer
When a money-transfer consumer exceeds its allowance, the gateway can respond with 429 Too Many Requests and Retry-After: Tue, 02 Jan 2024 14:12:00 GMT. For a banking-holiday interruption, the transfer endpoint can instead return 503 Service Unavailable with Retry-After: 3600 or a date indicating when transfers resume. section 13.2.2 section 14.2.3
Retry-After is not the only planned-unavailability strategy: valid requests may be accepted with 202 Accepted, status DELAYED, and a processingDate for later execution. Choose that approach only when the necessary checks can happen before execution and its risks are acceptable. section 14.2.3 section 14.9
