Retryability: Telling Clients What To Do Next

Retry behavior is not optional client politeness; it is forced by physics. Networks time out, connections reset, load balancers shed. Any client that wants to be reliable wraps calls in a retry loop — and if your contract is silent, the loop's policy is invented from folklore: "retry 5xx three times", "retry everything idempotent", "retry everything, it is probably fine". Multiply an invented policy by every consumer and you get the two standard disasters: permanent failures hammered thirty times each, and a synchronized retry storm that turns a 10-second blip into a 10-minute outage.

The contract's job is to replace guessing with three explicit answers per failure: can retrying help (card_declined: no, ever; 503: yes), when (Retry-After: 30, or "exponential backoff from 1s"), and is it safe — the answer that does not live in the error at all, but in the operation's idempotency contract (see Idempotency). A 504 on POST /payments is retryable by timing and catastrophic by safety unless Idempotency Keys: The Mechanism make the retry a no-op. Retryability guidance without an idempotency story is an invitation to duplicate side effects.

The hardest case is the one with no response: a timeout. The client cannot know whether the request was processed — the answer is genuinely unknowable from its side (see Retries and Timeouts as Contract Guidance). The contract cannot eliminate the ambiguity, but it decides whether the ambiguity is *safe*: with idempotency keys, "retry on timeout" is correct advice; without them, the honest documentation is "on timeout, reconcile by reading state before retrying" — advice almost no client follows, which is the argument for the keys.

Two mechanisms carry the guidance in the response itself, where the retry loop can see it. Retry-After (seconds, or an HTTP date) on 429 and 503 is the server telling the client something the client cannot compute: when capacity or quota will exist again. It converts a guessing game into a schedule — and it is a promise: a server that says Retry-After: 30 and still rejects at 31 seconds teaches clients to ignore the header, which un-designs the mechanism for everyone.

A body-level retryable: true|false flag (or equivalently, documented retryability per error code) covers what status classes cannot: two 409s may differ — stale_version is retryable after a re-read, duplicate_email is not retryable at all. The flag lets your SDK implement one loop — if (!err.retryable) throw — that is correct for every current and future error code, which matters because your SDK's loop is the retry policy most consumers will actually run (see SDK Design: The Contract's User Interface).

Backoff parameters belong in the docs rather than per-response: initial delay, multiplier, jitter, and a budget (max attempts or total time). Jitter is not an optimization but a herd-safety requirement — a thousand clients that all saw the same failure at the same moment and all retry at exactly 1s, 2s, 4s re-synchronize into waves that keep a recovering service down. Documented jitter is the contract's contribution to your own survivability.

You do not control the retry loops pointed at you; you shape them. Assume the worst client exists — no backoff, no jitter, no budget, retries 4xx — because at scale it does. Server-side rate limits are the backstop that makes the worst client survivable (see The Rate-Limit Contract); explicit retryability guidance is what keeps the *good* clients from accidentally behaving like the worst one during an incident. Both layers exist because the other one fails sometimes.

The storm dynamics are worth internalizing with numbers. Suppose 1,000 clients each send 1 rps and you blip for 10 seconds. Naive immediate-retry clients turn 10,000 failed requests into 10,000 instant retries stacked on top of live traffic — a 2x spike aimed at a service that just proved it cannot handle 1x. With exponential backoff, full jitter and a 3-attempt budget, the same failure spreads roughly the same retries over ~30 seconds as a gentle slope. Same clients, same outage, opposite recovery curve — the difference is only what the contract taught them to do.

Retry budgets are the piece most contracts forget: unbounded retrying converts one downstream outage into a memory-and-connection leak in every consumer, and a queue of stale retries that replays the load spike after recovery. "At most 3 attempts or 30 seconds, then surface the failure" is contract guidance, and it pairs with An Error Taxonomy Clients Can Branch On: budgets apply to dependency-class failures, never to validation-class ones, where the correct budget is zero.