2 min • read

Automatic retries

Sometimes requests fail. When these requests fail for transient issues, Emissary-ingress can automatically retry the request.

Retry policy can be set for all Emissary-ingress mappings in the ambassador Module, or set per Mapping. Generally speaking, you should set retry_policy on a per mapping basis. Global retries can easily result in unexpected cascade failures.

Note that when setting retry_policy, adjusting max_retries in the circuit breaker configuration should also be considered in order to account for all desired retries.

Configuring retries

The retry_policy attribute configures automatic retries. The following fields are supported:


(Required) Specifies the condition under which Emissary-ingress retries a failed request.

5xxRetries if the upstream service responds with any 5xx code or does not respond at all
gateway-errorSimilar to a 5xx but only applies to a 502, 503, or 504 response
connect-failureRetries on a connection failure to the upstream service (included in 5xx)
retriable-4xxRetries on a retriable 4xx response (currently only 409)
refused-streamRetires if the upstream service sends a REFUSED_STREAM error (included in 5xx)
retriable-status-codesRetries based on status codes set in the x-envoy-retriable-status-codes header. If that header isn't set, Emissary-ingress will not retry the request.

For more details on each of these values, see the Envoy documentation.


(Default: 1) Specifies the number of retries to execute for a failed request.


(Default: global request timeout) Specify the timeout for each retry. Must be in seconds or nanoseconds, e.g., 1s, 1500ns.


A per mapping retry policy:

A global retry policy (not recommended):