0004. Opt-in retries for idempotent calls only¶
- Status: Accepted
- Date: 2026-11-14
- Deciders: Sebastien Rousseau (suite alignment program, ships in 0.0.88)
Context¶
Until 0.0.88 the client sent every request once and the README told
callers to wrap it for retries. A pain001 serve behind a load
balancer answers 503 while it restarts, and a rate limiter answers 429
with Retry-After; every caller would write the same loop. The five
suite SDKs agreed one shape for it (Go WithRetry, Java, Rust, .NET
and C++ RetryPolicy).
Retrying is only safe when sending the request twice has the effect of
sending it once. validate, check and project_face are POSTs with
no side effect on the server today, but the API does not promise that,
and generate may be logged or billed by an operator. A retried POST
whose first attempt reached the server would do the work twice.
Options considered¶
- No retries; leave it to the caller (the 0.0.87 behaviour).
- Retries on by default for every call.
- An opt-in
RetryPolicythat retries GET only (health,faces,requestwith GET), on transport failures and on 429 and 503.
Decision¶
Option 3. ClientOptions::retry is a std::optional<RetryPolicy>,
unset by default, so 0.0.87 behaviour is unchanged. When set, a GET is
retried when the Transport throws TransportError (no response) or
the server answers 429 or 503, up to max_attempts attempts in total.
The wait doubles from initial_backoff up to max_backoff; with
jitter (the default) it is uniform in [0, wait] ("full jitter"). A
Retry-After in delta-seconds or IMF-fixdate form replaces the
computed wait; one longer than max_backoff ends the retries and the
response goes to the caller, so a server asking for an hour does not
block a thread for an hour. POST is never retried, whatever the
policy. max_backoff is capped at one hour and max_attempts must be
at least 1; anything else throws std::invalid_argument from the
Client constructor.
RetryPolicy::sleep replaces std::this_thread::sleep_for when set,
for callers with their own scheduler and for the tests, which record
every wait instead of sleeping.
Consequences¶
- The timeout in
ClientOptionsis per attempt; the worst case for a GET ismax_attempts * timeoutplus the waits. HttpResponsegainedheadersandheader()so the policy can readRetry-After. A customTransportthat does not fill them still works: the computed backoff is used.- 500, 502 and 504 are not retried: the server's 5xx other than 503
means a bug or a proxy failure, which a retry would hide. A caller
who wants that can wrap
request(). - The obsolete RFC 850 and asctime date forms of
Retry-Afterare not read; such a value falls back to the computed wait.