Retries & Backoff
Most important commands to remember
curl --retry 2— allow up to two retries after the initial attempt.curl --retry-max-time 10— limit the time window for starting retries.
Commands and flags
| Command or option | Meaning |
|---|---|
--silent --show-error |
Hide progress while retaining error diagnostics. |
--fail-with-body |
Return failure for HTTP errors while keeping their response bodies. |
--connect-timeout 1 --max-time 3 |
Bound connection setup to one second and each attempt to three seconds. |
--retry 2 |
Retry qualifying transient failures at most twice: up to three total attempts. |
--retry-max-time 10 |
Stop starting retries once the retry time window is exceeded. |
-i |
Include HTTP response headers. |
printf … "$?" |
Print curl’s final exit status immediately afterward. |
The retry window is not a hard total deadline: an already started attempt can finish beyond it. Curl applies its retry delay behavior and honors applicable Retry-After responses.
The concepts that matter
1. A retry asks whether another attempt can help
A retry repeats an operation after a failure or uncertain result. It can recover from a brief service interruption or transient network problem without requiring the user to intervene.
Not every failure is transient. Repeating invalid credentials or an unsupported request usually does not fix it. Decide which errors qualify and how many attempts are affordable. More attempts are additional work for both caller and dependency.
2. Backoff gives the dependency time to recover
Immediate repeated attempts can crowd a struggling service. Backoff spaces them out; exponential backoff increases the delay after successive failures up to a chosen bound.
Jitter varies delays across clients so they do not all return at the same instant. A deterministic delay shared by thousands of clients can synchronize traffic bursts. The curl example demonstrates bounded built-in retries, not a randomized production retry policy.
3. Idempotency determines whether repetition is safe
An idempotent operation has the same intended effect when repeated. That does not mean every response must be byte-identical, and it does not mean a failed response proves no effect occurred.
For actions such as creating an order, use a documented idempotency mechanism or reconcile the original result. A client-generated operation key is useful only if the server implements its semantics. Merely adding a header called an idempotency key does not create duplicate protection.
4. Retry budgets belong to the whole request
Retries consume the caller’s total time budget. If several layers each retry independently, the number of downstream attempts can multiply rather than simply add.
Choose the responsible retry layer, bound attempts and waiting, and stop when the result is no longer useful. During persistent failure, rejecting or deferring work can be more effective than repeatedly consuming the dependency’s remaining capacity. Recovery policy should match the operation and the failure mode.
One small example
Optional: use the reset test endpoint with the stated one-failure sequence. It must be a harmless GET endpoint; do not substitute an action-triggering URL. Run printf directly after curl.
curl --silent --show-error --fail-with-body --connect-timeout 1 --max-time 3 --retry 2 --retry-max-time 10 -i http://localhost:8080/flaky
printf 'curl_exit=%s\n' "$?"The first 503 qualifies for retry. If the next response arrives as configured, the final result should be 200 and curl should exit successfully. Headers or diagnostics may reveal multiple attempts; confirm the attempt count in the fixture’s request log if available.
A final success alone does not prove a retry occurred: the fixture may already have recovered before the first call. An unavailable endpoint can produce a different error that this policy does not retry. The commands create no files; reset only the dedicated fixture before repeating the same comparison.
Keep this idea: Retry only when repetition can help and is safe, with a shared time budget and enough spacing to avoid worsening the failure.