Retry-After

Retry-After is a standard HTTP response header through which the server informs the client, when returning a 429 or 503, how many seconds to wait before retrying.

The Retry-After header in an HTTP 429 response is used by the server to inform the client of the number of seconds to wait, and reading this value takes priority over calculating it independently.

The core idea of exponential backoff is that the wait time between retries grows exponentially, with random jitter added to avoid the thundering herd effect.

Anthropic documentation notes that a 429 response triggered by the monthly spending cap has no retry-after header and will keep failing until the quota resets.

Anthropic documentation explicitly requires clients to honor the retry-after header in 429 responses.

After honoring retry-after and layering full jitter on top, the last call completed at 11.8 seconds, 313 requests were sent, and p95 was 9.1 seconds, with every metric better than the two backoff formulas.

An Anthropic API 529 error indicates service overload and is usually accompanied by a Retry-After header; the official guidance is to retry 529 errors following a backoff strategy.

The Retry-After header has two formats: seconds (e.g. Retry-After: 120) or an HTTP date (e.g. Retry-After: Wed, 21 Oct 2026 07:28:00 GMT).

Services that conform to HTTP semantics often include a Retry-After response header when returning 429, indicating the recommended number of seconds to wait, and clients should prioritize following that value.

When a 429 is received, exponential backoff with random jitter should be implemented starting at about 500ms, and if a Retry-After response header is present, wait at least that long; ignoring Retry-After or retrying at fixed intervals will prolong the outage for the entire team.

For HTTP 429, the Retry-After header should be checked, and if present, its value should be used instead of the computed backoff delay.

Retry-After is an HTTP response header that the server uses to explicitly tell the client how long it should wait before retrying, and the unit can be seconds or an HTTP date; clients should prioritize obeying Retry-After, and only fall back to exponential backoff when that header is missing.

The retry loop in the code attempts at most 4 times, with exponential backoff starting at 500 milliseconds, and it prioritizes obeying the Retry-After response header when the service provides one.

Some APIs explicitly inform the client how many seconds to wait via the Retry-After response header in a 429 response, which is more precise than blind backoff.

For invalid Retry-After values, the SDK now ignores them directly and validates maxRetries.

v1.6.0 fixed the retry logic so the client respects Retry-After values exceeding 60 seconds, which previously would trigger premature retries due to an upper limit.

Some APIs include a Retry-After response header when returning 429 (Too Many Requests) to tell the client how long to wait, and that value should be used as the authoritative wait time.