API Reference

Decorator

This decorator wraps tenacity.retry with sensible defaults for retrying potentially transient HTTP errors. It's the most convenient way to leverage retryhttp.

retryhttp.retry

retry(func: F) -> F

retry(func: None = None, *, max_attempt_number: int = 3, retry_server_errors: bool = True, retry_network_errors: bool = True, retry_timeouts: bool = True, retry_rate_limited: bool = True, wait_server_errors: wait_base = wait_random_exponential(), wait_network_errors: wait_base = wait_exponential(), wait_timeouts: wait_base = wait_random_exponential(), wait_rate_limited: wait_base = wait_retry_after(), server_error_codes: Union[Sequence[int], int] = (500, 502, 503, 504), network_errors: Union[Type[BaseException], Tuple[Type[BaseException], ...], None] = None, timeouts: Union[Type[BaseException], Tuple[Type[BaseException], ...], None] = None, **kwargs: Any) -> Callable[[F], F]

retry(func: Optional[F] = None, *, max_attempt_number: int = 3, retry_server_errors: bool = True, retry_network_errors: bool = True, retry_timeouts: bool = True, retry_rate_limited: bool = True, wait_server_errors: wait_base = wait_random_exponential(), wait_network_errors: wait_base = wait_exponential(), wait_timeouts: wait_base = wait_random_exponential(), wait_rate_limited: wait_base = wait_retry_after(), server_error_codes: Union[Sequence[int], int] = (500, 502, 503, 504), network_errors: Union[Type[BaseException], Tuple[Type[BaseException], ...], None] = None, timeouts: Union[Type[BaseException], Tuple[Type[BaseException], ...], None] = None, **kwargs: Any) -> Union[F, Callable[[F], F]]

Retry potentially transient HTTP errors with sensible default behavior.

By default, retries the following errors, for a total of 3 attempts, with exponential backoff (except when rate limited, which defaults to the Retry-After header, if present):

HTTP status errors:
- 429 Too Many Requests (rate limited)
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Network errors:
- httpx.ConnectError
- httpx.ReadError
- httpx.WriteError
- requests.ConnectionError
- requests.exceptions.ChunkedEncodingError
- aiohttp.ClientConnectionError
Timeouts:
- httpx.TimeoutException
- requests.Timeout
- aiohttp.ServerTimeoutError

PARAMETER	DESCRIPTION
`max_attempt_number`	Total times to attempt a request. Includes the first attempt and any additional retries. TYPE: `int` DEFAULT: `3`
`retry_server_errors`	Whether to retry 5xx server errors. TYPE: `bool` DEFAULT: `True`
`retry_network_errors`	Whether to retry network errors. TYPE: `bool` DEFAULT: `True`
`retry_timeouts`	Whether to retry timeouts. TYPE: `bool` DEFAULT: `True`
`retry_rate_limited`	Whether to retry when `Retry-After` header received. TYPE: `bool` DEFAULT: `True`
`wait_server_errors`	Wait strategy to use for server errors. TYPE: `wait_base` DEFAULT: `wait_random_exponential()`
`wait_network_errors`	Wait strategy to use for network errors. TYPE: `wait_base` DEFAULT: `wait_exponential()`
`wait_timeouts`	Wait strategy to use for timeouts. TYPE: `wait_base` DEFAULT: `wait_random_exponential()`
`wait_rate_limited`	Wait strategy to use when `Retry-After` header received. TYPE: `wait_base` DEFAULT: `wait_retry_after()`
`server_error_codes`	One or more 5xx error codes that will trigger `wait_server_errors` if `retry_server_errors` is `True`. Defaults to 500, 502, 503, and 504. TYPE: `Union[Sequence[int], int]` DEFAULT: `(500, 502, 503, 504)`
`network_errors`	One or more exceptions that will trigger `wait_network_errors` if `retry_network_errors` is `True`. Defaults to: `httpx.ConnectError` `httpx.ReadError` `httpx.WriteError` `requests.ConnectError` `requests.exceptions.ChunkedEncodingError` `aiohttp.ClientConnectionError` TYPE: `Union[Type[BaseException], Tuple[Type[BaseException], ...], None]` DEFAULT: `None`
`timeouts`	One or more exceptions that will trigger `wait_timeouts` if `retry_timeouts` is `True`. Defaults to: `httpx.TimeoutException` `requests.Timeout` `aiohttp.ServerTimeoutError` TYPE: `Union[Type[BaseException], Tuple[Type[BaseException], ...], None]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Union[F, Callable[[F], F]]`	Decorated function.

RAISES	DESCRIPTION
`RuntimeError`	If `retry_server_errors`, `retry_network_errors`, `retry_timeouts`, and `retry_rate_limited` are all `False`.

Retry Strategies

If you'd rather use tenacity.retry directly (without using retryhttp.retry), you can use these retry strategies.

retryhttp.retry_if_network_error

Bases: retry_if_exception_type

Retry network errors.

PARAMETER	DESCRIPTION
`errors`	One or more exceptions to consider a network error. If omitted, defaults to: `httpx.ConnectError` `httpx.ReadError` `httpx.WriteError` `requests.ConnectionError` `requests.exceptions.ChunkedEncodingError` `aiohttp.ClientConnectionError` TYPE: `Union[Type[BaseException], Tuple[Type[BaseException], ...], None]` DEFAULT: `None`

retryhttp.retry_if_rate_limited

Bases: retry_base

Retry if server responds with a Retry-After header.

retryhttp.retry_if_server_error

Bases: retry_base

Retry certain server errors (5xx).

PARAMETER	DESCRIPTION
`server_error_codes`	One or more 5xx errors to retry. TYPE: `Union[Sequence[int], int]` DEFAULT: `(500, 502, 503, 504)`

retryhttp.retry_if_timeout

Bases: retry_if_exception_type

Retry timeouts.

PARAMETER	DESCRIPTION
`timeouts`	One or more exceptions to consider a timeout. If omitted, defaults to: `httpx.ConnectTimeout` `httpx.ReadTimeout` `httpx.WriteTimeout` `requests.Timeout` `aiohttp.ClientConnectionError` TYPE: `Union[Type[BaseException], Tuple[Type[BaseException], ...], None]` DEFAULT: `None`

Wait Strategies

Wait strategies to use with tenacity.retry or retryhttp.retry.

retryhttp.wait_from_header

Bases: wait_base

Wait strategy that derives the wait value from an HTTP header.

Value may be either an integer representing the number of seconds to wait before retrying, or a future datetime in HTTP-date format, indicating when it is acceptable to retry the request.

More info on HTTP-date format: https://httpwg.org/specs/rfc9110.html#http.date

PARAMETER	DESCRIPTION
`header`	Header to attempt to derive wait value from. TYPE: `str`
`wait_max`	Maximum time to wait, in seconds. Defaults to 120.0s. If `None` is given, will wait indefinitely. Use `Non` with caution, as your program will hang if the server responds with an excessive wait value. TYPE: `float` DEFAULT: `120.0`
`fallback`	Wait strategy to use if `header` is not present, or unable to parse to a `float` value, or if value parsed from header exceeds `wait_max`. Defaults to `tenacity.wait_exponential`. TYPE: `wait_base` DEFAULT: `wait_exponential()`

RAISES	DESCRIPTION
`ValueError`	If `fallback` is `None`, and any one of the following is true: * header is not present; * the value cannot be parsed to a `float`; * the value exceeds `wait_max`; * the value is a date in the past.

retryhttp.wait_context_aware

Bases: wait_base

Uses a different wait strategy based on the type of HTTP error.

PARAMETER	DESCRIPTION
`wait_server_errors`	Wait strategy to use with server errors. TYPE: `wait_base` DEFAULT: `wait_retry_after(fallback=wait_random_exponential())`
`wait_network_errors`	Wait strategy to use with network errors. TYPE: `wait_base` DEFAULT: `wait_exponential()`
`wait_timeouts`	Wait strategy to use with timeouts. TYPE: `wait_base` DEFAULT: `wait_random_exponential()`
`wait_rate_limited`	Wait strategy to use when rate limited. TYPE: `wait_base` DEFAULT: `wait_retry_after(fallback=wait_exponential())`
`server_error_codes`	One or more 5xx HTTP status codes that will trigger `wait_server_errors`. TYPE: `Union[Sequence[int], int]` DEFAULT: `(500, 502, 503, 504)`
`network_errors`	One or more exceptions that will trigger `wait_network_errors`. If omitted, defaults to: `httpx.ConnectError` `httpx.ReadError` `httpx.WriteError` `requests.ConnectionError` `requests.exceptions.ChunkedEncodingError` `aiohttp.ClientConnectionError` TYPE: `Union[Type[BaseException], Tuple[Type[BaseException], ...], None]` DEFAULT: `None`
`timeouts`	One or more exceptions that will trigger `wait_timeouts`. If omitted, defaults to: `httpx.ConnectTimeout` `httpx.ReadTimeout` `httpx.WriteTimeout` `requests.Timeout` `aiohttp.ServerTimeoutError` TYPE: `Union[Type[BaseException], Tuple[Type[BaseException], ...], None]` DEFAULT: `None`

retryhttp.wait_retry_after

Bases: wait_from_header

Wait strategy to use when the server responds with a Retry-After header.

The header value may provide a date for when you may retry the request, or an integer, indicating the number of seconds to wait before retrying.

PARAMETER	DESCRIPTION
`wait_max`	Maximum time to wait, in seconds. Defaults to 120.0s. If `None` is given, will wait indefinitely. Use `Non` with caution, as your program will hang if the server responds with an excessive wait value. TYPE: `float` DEFAULT: `120.0`
`fallback`	Wait strategy to use if `header` is not present, or unable to parse to a `float` value, or if value parsed from header exceeds `wait_max`. Defaults to `tenacity.wait_exponential()`. TYPE: `wait_base` DEFAULT: `wait_exponential()`

RAISES	DESCRIPTION
`ValueError`	If `fallback` is `None`, and any one of the following is true: * `Retry-After` header is not present; * the value cannot be parsed to a `float`; * the value exceeds `wait_max`; * the value is a date in the past.