backends.http.retry
retry
The request_error and request-error retry conditions are equivalent. Prefer
request_error.
The optional retry block repeats an HTTP backend request before its result is
treated as the terminal service result. Only the terminal result updates reply,
error, timeout, latency, and service-level-objective state. Each additional
attempt increments the backend Retries counter.
The top-level timeout applies
separately to every attempt. delay sets the base wait before each retry and
supports duration units. When delay is
omitted, its base value is 10% of the per-request timeout. The optional
jitter parameter adds an independently selected random duration from 0ms
through its configured value to every wait. This matches the random-addition
model used by the sleep action. Configure delay 0ms
without jitter to retry without waiting. A
backend action timeout remains a single
deadline for the complete logical operation, including retry delays and
response bodies.
retries is required and counts additional attempts after the initial request.
For example, retries 2 allows at most three attempts. Generic HTTP, Duo, and
RSA-AM backends default to no retries when this block is omitted. The YubiKey
backend defaults to two retries, following the
Yubico OTP validation protocol
recommendation to retry transient HTTP failures a few times.
With no on statements, every timeout, request error, and non-success HTTP
status is retryable. Add one or more on statements to restrict the policy:
on timeout;retries per-attempt timeouts.on request_error;retries transport and request errors other than timeouts.on 4xx;oron 5xx;retries every status in that HTTP status class. Classes from1xxthrough5xxare supported.on 503;retries exactly that HTTP status code. Repeat the statement for additional codes.on all;explicitly selects the default matching policy and cannot be mixed with other conditions.
backends {
http "api" {
url "https://api.example.com";
timeout 2s;
retry {
retries 3;
delay 250ms;
jitter 100ms;
on timeout;
on request_error;
on 429;
on 5xx;
}
}
}
Retries resend the same HTTP method, headers, and body. Before enabling retries for requests that change remote state, ensure the endpoint is idempotent or supports an idempotency key.