Retries and Timeouts as Contract Guidance

Every failure a client sees is one of two kinds, and the difference governs everything downstream. A definitive failure — 400, 403, 422 — is an answer: the server judged the request and rejected it, and retrying the identical request is pure waste. A timeout is *no answer*: the request may have never arrived, arrived and failed, or arrived and fully succeeded with the response lost in flight. The client cannot distinguish these, which is why retrying a timed-out mutation is only safe under Idempotency — the timeout is the precise scenario idempotency keys exist for.

The client's timeout is a contract-adjacent number, and the API should inform it. Publish latency expectations per operation class (reads p99 < 500ms, writes p99 < 2s) so clients can set timeouts above real p99 instead of guessing: a timeout below server p99 manufactures failures out of successes — the client abandons requests the server completes, then retries them, doubling load and duplicating effects. And keep your own upstream budget shorter than what you expect clients to wait, so you can return a real 504 with guidance instead of letting the client's deadline fire first and learn nothing (Status Codes Clients Can Branch On).

Left to defaults, every client invents its own loop, and the bad ones share a shape: immediate retry, fixed interval, unlimited attempts. Immediate retry hits a server still in the same failing state. Fixed intervals synchronize clients that failed together into waves that arrive together. Unlimited attempts convert a five-minute incident into an hour of self-sustained load. The fix is a published recipe: exponential backoff (double the wait per attempt: 1s, 2s, 4s, 8s…), full jitter (each wait is random(0, base × 2^attempt) — the randomness is what breaks up the waves), a cap on both single-wait and total attempts, and a retry budget (retries as a bounded fraction of a client's traffic, ~10–20%, so retry load can never dominate first-try load).

Server-sent timing beats client math wherever you can provide it: Retry-After on 429 and 503 is you telling clients exactly when capacity returns, which no backoff formula can know (The Rate-Limit Contract). And publish where retries should *stop* mattering: after the budget is spent, the correct client behavior is to surface the failure — to a queue, a dead-letter, a human — not to keep pounding. Clients with a circuit-breaking layer (Circuit Breaker) formalize exactly this.

One structural rule prevents the worst emergent behavior: retry at one layer. When the SDK retries 3×, the calling service retries 3×, and its caller retries 3×, one user action becomes 27 requests — retry amplification that turns a hiccup into an outage. The contract should say where the retry responsibility lives (usually: the SDK, with everything above it failing fast), because no single team can see the multiplication from inside its own layer.

Everything above becomes real only when it is written into the contract per failure mode — a retryability column in the error table, not a paragraph of general advice (Retryability: Telling Clients What To Do Next covers the response-side signaling; An Error Taxonomy Clients Can Branch On the classification it hangs on). The reference APIs ship this as SDK behavior, which is the strongest form of documentation: Stripe's and AWS's SDKs retry idempotent operations with jittered backoff by default, which means the *median* integration is well-behaved without its author ever reading the retry section.

The server side must then enforce what it published, because during an incident you will meet the clients who ignored it. Rate limits that apply to retry storms (The Rate-Limit Contract), load shedding that answers excess load with fast 503 + Retry-After instead of slow timeouts, and idempotency machinery sized for retry bursts (Idempotency Keys: The Mechanism) are the enforcement half. A contract that politely requests backoff while the server melts under whoever ignores it is a contract that punishes exactly the compliant.