backends.http.retry

retry

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; or on 5xx; retries every status in that HTTP status class. Classes from 1xx through 5xx are 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.