RetryPolicy Class

Reference

A retry policy.

The retry policy in the pipeline can be configured directly, or tweaked on a per-call basis.

Inheritance: azure.core.pipeline.policies._retry.RetryPolicyBase

RetryPolicy

azure.core.pipeline.policies._base.HTTPPolicy

RetryPolicy

Constructor

RetryPolicy(**kwargs: Any)

Keyword-Only Parameters

Name	Description
retry_total	int Total number of retries to allow. Takes precedence over other counts. Default value is 10.
retry_connect	int How many connection-related errors to retry on. These are errors raised before the request is sent to the remote server, which we assume has not triggered the server to process the request. Default value is 3.
retry_read	int How many times to retry on read errors. These errors are raised after the request was sent to the server, so the request may have side-effects. Default value is 3.
retry_status	int How many times to retry on bad status codes. Default value is 3.
retry_backoff_factor	float A backoff factor to apply between attempts after the second try (most errors are resolved immediately by a second try without a delay). In fixed mode, retry policy will always sleep for {backoff factor}. In 'exponential' mode, retry policy will sleep for: {backoff factor} (2 ** ({number of total retries} - 1))* seconds. If the backoff_factor is 0.1, then the retry will sleep for [0.0s, 0.2s, 0.4s, ...] between retries. The default value is 0.8.
retry_backoff_max	int The maximum back off time. Default value is 120 seconds (2 minutes).
retry_mode	RetryMode Fixed or exponential delay between attemps, default is exponential.
timeout	int Timeout setting for the operation in seconds, default is 604800s (7 days).

Examples

Configuring a retry policy.


   from azure.core.pipeline.policies import RetryPolicy

   retry_policy = RetryPolicy()

   # Total number of retries to allow. Takes precedence over other counts.
   # Default value is 10.
   retry_policy.total_retries = 5

   # How many connection-related errors to retry on.
   # These are errors raised before the request is sent to the remote server,
   # which we assume has not triggered the server to process the request. Default value is 3
   retry_policy.connect_retries = 2

   # How many times to retry on read errors.
   # These errors are raised after the request was sent to the server, so the
   # request may have side-effects. Default value is 3.
   retry_policy.read_retries = 4

   # How many times to retry on bad status codes. Default value is 3.
   retry_policy.status_retries = 3

   # A backoff factor to apply between attempts after the second try
   # (most errors are resolved immediately by a second try without a delay).
   # Retry policy will sleep for:
   #    {backoff factor} * (2 ** ({number of total retries} - 1))
   # seconds. If the backoff_factor is 0.1, then the retry will sleep
   # for [0.0s, 0.2s, 0.4s, ...] between retries.
   # The default value is 0.8.
   retry_policy.backoff_factor = 0.5

   # The maximum back off time. Default value is 120 seconds (2 minutes).
   retry_policy.backoff_max = 120

   # Alternatively you can disable redirects entirely
   retry_policy = RetryPolicy.no_retries()

   # All of these settings can also be configured per operation.
   policies.append(retry_policy)
   client: PipelineClient[HttpRequest, HttpResponse] = PipelineClient(base_url=url, policies=policies)
   request = HttpRequest("GET", url)
   pipeline_response = client._pipeline.run(
       request,
       retry_total=10,
       retry_connect=1,
       retry_read=1,
       retry_status=5,
       retry_backoff_factor=0.5,
       retry_backoff_max=120,
       retry_on_methods=["GET"],
   )

Methods

configure_retries	Configures the retry settings.
get_backoff_time	Returns the current backoff time.
get_retry_after	Get the value of Retry-After in seconds.
increment	Increment the retry counters.
is_exhausted	Checks if any retries left.
is_retry	Checks if method/status code is retryable. Based on allowlists and control variables such as the number of total retries to allow, whether to respect the Retry-After header, whether this header is present, and whether the returned status code is on the list of status codes to be retried upon on the presence of the aforementioned header. The behavior is: `If status_code < 400: don't retry` `Else if Retry-After present: retry` `Else: retry based on the safe status code list ([408, 429, 500, 502, 503, 504])`
no_retries	Disable retries.
parse_retry_after	Helper to parse Retry-After and get value in seconds.
send	Sends the PipelineRequest object to the next policy. Uses retry settings if necessary.
sleep	Sleep between retry attempts. This method will respect a server's `Retry-After` response header and sleep the duration of the time requested. If that is not present, it will use an exponential backoff. By default, the backoff factor is 0 and this method will return immediately.
update_context	Updates retry history in pipeline context.

configure_retries

Configures the retry settings.

configure_retries(options: Dict[str, Any]) -> Dict[str, Any]

Parameters

Name	Description
options Required	dict keyword arguments from context.

Returns

Type	Description
dict	A dict containing settings and history for retries.

get_backoff_time

Returns the current backoff time.

get_backoff_time(settings: Dict[str, Any]) -> float

Parameters

Name	Description
settings Required	dict The retry settings.

Returns

Type	Description
float	The current backoff value.

get_retry_after

Get the value of Retry-After in seconds.

get_retry_after(response: PipelineResponse[Any, AllHttpResponseType]) -> float | None

Parameters

Name	Description
response Required	PipelineResponse The PipelineResponse object

Returns

Type	Description
float, None	Value of Retry-After in seconds.

increment

Increment the retry counters.

increment(settings: Dict[str, Any], response: PipelineRequest[HTTPRequestType] | PipelineResponse[HTTPRequestType, AllHttpResponseType] | None = None, error: Exception | None = None) -> bool

Parameters

Name	Description
settings Required	dict The retry settings.
response	PipelineResponse A pipeline response object. default value: None
error	AzureError An error encountered during the request, or None if the response was received successfully. default value: None

Returns

Type	Description
bool	Whether any retry attempt is available True if more retry attempts available, False otherwise

is_exhausted

Checks if any retries left.

is_exhausted(settings: Dict[str, Any]) -> bool

Parameters

Name	Description
settings Required	dict the retry settings

Returns

Type	Description
bool	False if have more retries. True if retries exhausted.

is_retry

Checks if method/status code is retryable.

Based on allowlists and control variables such as the number of total retries to allow, whether to respect the Retry-After header, whether this header is present, and whether the returned status code is on the list of status codes to be retried upon on the presence of the aforementioned header.

The behavior is:

```
  If status_code < 400: don't retry
```
```
  Else if Retry-After present: retry
```

  Else: retry based on the safe status code list ([408, 429, 500, 502, 503, 504])

is_retry(settings: Dict[str, Any], response: PipelineResponse[HTTPRequestType, AllHttpResponseType]) -> bool

Parameters

Name	Description
settings Required	dict The retry settings.
response Required	PipelineResponse The PipelineResponse object

Returns

Type	Description
bool	True if method/status code is retryable. False if not retryable.

no_retries

Disable retries.

no_retries() -> ClsRetryPolicy

Returns

Type	Description
RetryPolicy, AsyncRetryPolicy	A retry policy with retries disabled.

parse_retry_after

Helper to parse Retry-After and get value in seconds.

parse_retry_after(retry_after: str) -> float

Parameters

Name	Description
retry_after Required	str Retry-After header

Returns

Type	Description
float	Value of Retry-After in seconds.

send

Sends the PipelineRequest object to the next policy. Uses retry settings if necessary.

send(request: PipelineRequest[HTTPRequestType]) -> PipelineResponse[HTTPRequestType, HTTPResponseType]

Parameters

Name	Description
request Required	PipelineRequest The PipelineRequest object

Returns

Type	Description
PipelineResponse	Returns the PipelineResponse or raises error if maximum retries exceeded.

Exceptions

Type	Description
azure.core.exceptions.AzureError if maximum retries exceeded.
azure.core.exceptions.ClientAuthenticationError if authentication

sleep

Sleep between retry attempts.

This method will respect a server's Retry-After response header and sleep the duration of the time requested. If that is not present, it will use an exponential backoff. By default, the backoff factor is 0 and this method will return immediately.

sleep(settings: Dict[str, Any], transport: HttpTransport[HTTPRequestType, HTTPResponseType], response: PipelineResponse[HTTPRequestType, HTTPResponseType] | None = None) -> None

Parameters

Name	Description
settings Required	dict The retry settings.
transport Required	HttpTransport The HTTP transport type.
response	PipelineResponse The PipelineResponse object. default value: None

update_context

Updates retry history in pipeline context.

update_context(context: PipelineContext, retry_settings: Dict[str, Any]) -> None

Parameters

Name	Description
context Required	PipelineContext The pipeline context.
retry_settings Required	dict The retry settings.

Attributes

BACKOFF_MAX

Maximum backoff time.

BACKOFF_MAX = 120

Pointer to the next policy or a transport (wrapped as a policy). Will be set at pipeline creation.

next: HTTPPolicy[HTTPRequestType, HTTPResponseType]

RetryPolicy Class

Constructor

Keyword-Only Parameters

Examples

Methods

configure_retries

Parameters

Returns

get_backoff_time

Parameters

Returns

get_retry_after

Parameters

Returns

increment

Parameters

Returns

is_exhausted

Parameters

Returns

is_retry

Parameters

Returns

no_retries

Returns

parse_retry_after

Parameters

Returns

send

Parameters

Returns

Exceptions

sleep

Parameters

update_context

Parameters

Attributes

BACKOFF_MAX

next

Feedback

Additional resources