RetryPolicy Class

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

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

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

keyword arguments from context.

Returns

Type Description

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

The retry settings.

Returns

Type Description

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

The PipelineResponse object

Returns

Type Description

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

The retry settings.

response

A pipeline response object.

Default value: None
error

An error encountered during the request, or None if the response was received successfully.

Default value: None

Returns

Type Description

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

the retry settings

Returns

Type Description

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

The retry settings.

response
Required

The PipelineResponse object

Returns

Type Description

True if method/status code is retryable. False if not retryable.

no_retries

Disable retries.

no_retries() -> ClsRetryPolicy

Returns

Type Description

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

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

The PipelineRequest object

Returns

Type Description

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

The retry settings.

transport
Required

The HTTP transport type.

response

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

The pipeline context.

retry_settings
Required

The retry settings.

Attributes

BACKOFF_MAX

Maximum backoff time.

BACKOFF_MAX = 120

next

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

next: HTTPPolicy[HTTPRequestType, HTTPResponseType]