Retry

APPLIES TO: All API Management tiers

The retry policy executes its child policies once and then retries their execution until the retry condition becomes false or retry count is exhausted.

The retry policy may contain any other policies as its child elements, except for wait policy.

Note

Set a policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

<retry
    condition="Boolean expression or literal"
    count="number of retry attempts"
    interval="retry interval in seconds"
    max-interval="maximum retry interval in seconds"
    delta="retry interval delta in seconds"
    first-fast-retry="boolean expression or literal">
        <!-- One or more child policies. No restrictions. -->
</retry>

Attributes

Attribute Description Required Default
condition Boolean. Specifies whether retries should be stopped (false) or continued (true). Policy expressions are allowed. Yes N/A
count A positive number between 1 and 50 specifying the number of retries to attempt. Policy expressions are allowed. Yes N/A
interval A positive number in seconds specifying the wait interval between the retry attempts. Policy expressions are allowed. Yes N/A
max-interval A positive number in seconds specifying the maximum wait interval between the retry attempts. It is used to implement an exponential retry algorithm. Policy expressions are allowed. No N/A
delta A positive number in seconds specifying the wait interval increment. It is used to implement the linear and exponential retry algorithms. Policy expressions are allowed. No N/A
first-fast-retry Boolean. If set to true, the first retry attempt is performed immediately. Policy expressions are allowed. No false

Retry wait times

  • When only the interval is specified, fixed interval retries are performed.

  • When only the interval and delta are specified, a linear interval retry algorithm is used. The wait time between retries increases according to the following formula: interval + (count - 1)*delta.

  • When the interval, max-interval and delta are specified, an exponential interval retry algorithm is applied. The wait time between the retries increases exponentially according to the following formula: interval + (2^(count - 1)) * random(delta * 0.8, delta * 1.2), up to a maximum interval set by max-interval.

    For example, when interval and delta are both set to 10 seconds, and max-interval is 100 seconds, the approximate wait time between retries increases as follows: 10 seconds, 20 seconds, 40 seconds, 80 seconds, with 100 seconds wait time used for remaining retries.

Elements

The retry policy may contain any other policies as its child elements, except for wait policy.

Usage

Usage notes

  • The policy executes the child policies in the retry block before it evaluates the condition for executing the first retry attempt.

Examples

Request forwarding with exponential retry

In the following example, request forwarding is retried up to ten times using an exponential retry algorithm. Since first-fast-retry is set to false, all retry attempts are subject to exponentially increasing retry wait times (in this example, approximately 10 seconds, 20 seconds, 40 seconds, ...), up to a maximum wait of max-interval.

<retry
    condition="@(context.Response.StatusCode == 500)"
    count="10"
    interval="10"
    max-interval="100"
    delta="10"
    first-fast-retry="false">
        <forward-request buffer-request-body="true" />
</retry>

Send request upon initial request failure

In the following example, sending a request to a URL other than the defined backend is retried up to three times if the connection is dropped/timed out, or the request results in a server-side error. Since first-fast-retry is set to true, the first retry is executed immediately upon the initial request failure. Note that send-request must set ignore-error to true in order for response-variable-name to be null in the event of an error.


<retry
    condition="@(context.Variables["response"] == null || ((IResponse)context.Variables["response"]).StatusCode >= 500)"
    count="3"
    interval="1"
    first-fast-retry="true">
        <send-request 
            mode="new" 
            response-variable-name="response" 
            timeout="3" 
            ignore-error="true">
		        <set-url>https://api.contoso.com/products/5</set-url>
		        <set-method>GET</set-method>
		</send-request>
</retry>

Switch backend when error received

In the following example, the initial request is dispatched to the primary backend. If a 429 Too Many Requests response status code is returned, the request is retried immediately and forwarded to the secondary backend.

<backend>
    <retry
        condition="@(context.Response != null && context.Response.StatusCode == 429)"
        count="1"
        interval="1"
        first-fast-retry="true">
           <set-variable name="attempt-count" value="@(context.Variables.GetValueOrDefault<int>("attempt-count", 0)+1)" />
           <set-backend-service backend-id="@(context.Variables.GetValueOrDefault<int>("attempt-count") < 2 ? "primary-backend" : "secondary-backend" )" />
           <forward-request />
    </retry>
</backend>

Tip

As an alternative, you can configure a backend resource with circuit breaker rules to detect failure conditions and a load-balanced pool that distributes requests across multiple backends.

Next steps

For more information about working with policies, see: