ADR 0004: Retries are opt-in and cover GET calls only¶
- Status: Accepted
- Date: 2026-11-14
Context¶
A server behind a load balancer answers the odd 503 or 429 while an
instance restarts or sheds load. Retrying hides that, but a retried
POST /api/v1/ui/generate is a second payment file, and a client that
retries by default changes behaviour under callers who never asked.
Decision¶
Pain001ClientOptions.Retry takes a RetryPolicy; it is null by
default, and then every request is sent once, as before. With a policy:
- only a
GETis retried:HealthAsync,FacesAsyncandRequestAsyncwithGET. APOSTnever is, whatever the policy; - it retries HTTP 429 and 503, and
HttpRequestException(a connection error); not other statuses, a timeout or a cancellation; - up to
MaxAttempts(default 3) attempts in all, waiting a jittered exponential backoff: half to all ofmin(MaxDelay, InitialDelay × 2^(n-1))(defaults 200 ms and 5 s); - a
Retry-Afterheader (seconds or an HTTP date) replaces the backoff; one longer thanMaxDelayreturns the answer instead of waiting.
Pain001ClientOptions.TimeProvider is the clock it waits on, so tests
run without sleeping. The suite specifies the same policy for every
SDK, under each language's own name (Go WithRetry; Java, Rust and C++
RetryPolicy).
Consequences¶
- Behaviour is unchanged for existing callers.
- A caller who needs payment calls retried makes that decision in their own code, with their own idempotency handling.
Timeoutstays per attempt: with retries, a call can take up toMaxAttempts × Timeoutplus the waits.