Radiator Server Documentation — v10.34.2
Table of Contents

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; 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.