The Retry-After response header tells an HTTP client how long the server wants it to wait before a follow-up request. The value is either a number of seconds or an HTTP date. It is useful with rate limiting and temporary service outages, but it is only one part of a safe retry policy.

Documentation checked: October 29, 2026. This guide follows RFC 9110 for the header and 503 semantics, RFC 6585 for 429, and AWS reliability guidance for bounded backoff and jitter.

The two valid forms

RFC 9110 defines two forms:

Retry-After: 120

This means wait 120 seconds after receiving the response.

Retry-After: Thu, 29 Oct 2026 05:00:00 GMT

This gives an absolute HTTP date. A client needs a current clock to turn that date into a delay.

The seconds form avoids clock-skew problems and is usually easier for API clients. The date form can describe a maintenance window that ends at a known time. In both cases, a client should reject a negative computed delay, cap an unreasonable value, and stop waiting when its own request deadline expires.

What 429 means

A 429 Too Many Requests response says the client has sent too many requests in a given amount of time. RFC 6585 says the response should explain the condition and may include Retry-After.

The standard does not dictate how the server counts requests. A limit may apply to an API key, account, IP address, resource, route or the whole service. That is why a client should read the response body and the provider’s current documentation instead of assuming every 429 has the same scope.

A 429 without Retry-After still calls for restraint. Use the API’s documented retry policy when it has one. Otherwise, apply bounded exponential backoff with jitter and a maximum elapsed time.

What 503 means

A 503 Service Unavailable response means the server is temporarily unable to handle the request, commonly because of overload or scheduled maintenance. RFC 9110 allows the server to send Retry-After to suggest how long the condition should last.

A 503 is different from a permanent client error. Repeating a malformed request or a request with invalid credentials will not become valid because time passed. Retrying a temporary capacity failure can help, provided the retry does not add enough traffic to prolong the outage.

The standard also notes that an overloaded service is not required to emit 503. It may refuse the connection instead. A production policy therefore needs to cover timeouts and connection failures as well as explicit status codes.

Honor Retry-After, then apply your own limits

When the server supplies a valid Retry-After, treat it as the minimum wait for that response. Your client still needs a ceiling.

A practical policy can be:

  1. Check whether the operation is safe to repeat.
  2. Parse Retry-After as delay-seconds or an HTTP date.
  3. Clamp the delay to zero or more.
  4. Stop if the delay exceeds the request’s total deadline.
  5. Add a small amount of jitter when many clients may resume together.
  6. Limit attempts and total elapsed time.
  7. Record the reason, attempt number and chosen delay.

The last step matters in production. Without it, a slow request can look like an application hang instead of a deliberate wait.

Why jitter still matters

Suppose a service tells 10,000 clients to retry after 60 seconds. If all of them resume at the same instant, the service can receive another sharp spike. Jitter spreads those attempts across a short window.

AWS’s Well-Architected guidance recommends exponential backoff, jitter and a maximum retry count. It also warns against retries at several layers of the same call stack. If a framework, SDK, proxy and application each retry three times, one user action can multiply into many backend calls.

Do not add jitter that makes the client retry before the server’s stated delay. Add it after the minimum wait, or use it within a provider’s documented retry window.

A bounded retry sketch

This language-neutral sketch keeps the server’s instruction and the client’s budget separate:

deadline = now + 30 seconds
attempt = 0

while now < deadline:
    response = send_request()

    if response is successful:
        return response

    if response is not retryable:
        return response

    minimum = parse_retry_after(response) or 0
    backoff = min(2 ^ attempt, 8 seconds)
    delay = max(minimum, backoff) + random_jitter()

    if now + delay >= deadline:
        return response

    wait(delay)
    attempt += 1

The numbers are examples, not universal defaults. A background export can tolerate a longer budget than an interactive checkout. Use the provider’s SDK and documented settings when available.

Retrying writes needs an idempotency decision

A retry can repeat an operation after the first attempt actually succeeded but its response was lost. That is harmless for many reads. It can duplicate a payment, message or job when a write is not idempotent.

Before retrying a state-changing request, confirm that the API provides an idempotency key or another way to recognize the same logical operation. Webtamine’s guide to idempotency keys explains how a server stores and replays the result of one request key.

HTTP method names help, but they are not a complete application guarantee. An API can attach side effects to an otherwise repeatable-looking request. Follow the provider’s contract.

Do not retry every error

Retry temporary failures. Fail fast when waiting will not change the result.

Common cases that usually need a fix rather than a retry include invalid credentials, missing permission, malformed input and an unsupported operation. A client may retry some conflicts or not-found responses when the API documents eventual consistency, but that is product-specific behavior.

Also avoid infinite retries. A queue that keeps retrying forever can outlive the business operation, hide an outage and create a backlog that becomes a second failure.

Server-side guidance

If you operate the API, send a Retry-After value that matches the real recovery window. A rate-limit response should explain which limit was reached when disclosing that information is safe. A maintenance 503 should not promise a date the service cannot meet.

Keep the response consistent with other rate-limit fields. Clients should not have to choose between contradictory instructions. If recovery time is unknown, omit a fabricated exact value and document the client’s fallback behavior.