4. Retries are opt-in and for GET only¶
- Status: accepted
- Date: 2026-11-14
Context¶
A client that reaches pain001 through a load balancer, or while the
server restarts, sees refused connections, timeouts, 429 and 503
answers that a second try would clear. Until 0.0.88 the client sent every
request exactly once, so each caller wrapped health and faces in a
loop of its own.
Retrying is not free. validate, generate, check and project_face
are POST calls that carry a payment file. A timeout does not say whether
the server processed the request, so retrying one could submit the same
file twice. The suite's five SDKs agreed on one behaviour.
Decision¶
RetryPolicy, set with Client::retry, retries GET calls only:
health, faces, and request with "GET". Without a policy the client
makes one attempt per call, as before.
- Retried:
Error::Transport(connection refused, timeout, TLS, a body cut short), and HTTP429and503. - Attempts:
max_attemptsin all, 3 by default;1retries nothing. - Wait before retry
n: a random point in the upper half ofmin(max_delay, base_delay * 2^(n-1)); 200 ms and 5 s by default. Retry-Afteron a429or503, in delta-seconds or as an IMF-fixdate, is waited exactly. One longer thanmax_delayends the retries and returns that answer, so the client never returns earlier than the server asked.- The client timeout applies to each attempt, not to the call as a
whole: ureq's timeout is per request, and a shared deadline would add
per-request configuration for little gain. The worst case is
max_attempts * timeoutplus the waits, which the policy bounds. - Jitter comes from the standard library's
RandomState, so retries add no dependency.
The names and defaults match the Go, Java, .NET and C++ SDKs.
Consequences¶
- Behaviour is unchanged for every existing caller.
- A
POSTthat fails is the caller's to retry, with whatever knowledge it has of whether the server acted on it. - The obsolete RFC 850 and asctime date forms are not read; such a
Retry-Afterfalls back to the backoff.