aiohttp-retry

2.9.1 verified Tue May 12 auth: no python install: verified

aiohttp-retry is a simple retry client for aiohttp, providing robust request retrying capabilities for asynchronous HTTP operations. It supports various retry strategies like exponential backoff and random delays. The current version is 2.9.1 and it requires Python 3.7 or higher. The library is actively maintained with regular releases addressing bug fixes and introducing new features.

pip install aiohttp-retry

Common errors

error ModuleNotFoundError: No module named 'aiohttp' ↓

cause The 'aiohttp' package is not installed or not accessible in the current Python environment.

fix

Ensure 'aiohttp' is installed in the correct environment by running 'python3.6 -m pip install aiohttp'.

error message='Attempt to decode JSON with unexpected mimetype: text/html; charset=utf-8' ↓

cause The server responded with a non-JSON content type, causing a JSON decoding error.

fix

Implement error handling to manage unexpected content types and consider retrying the request upon failure.

error ClientConnectorError: Cannot connect to host example.com:443 ssl:default [Connect call failed] ↓

cause The client is unable to establish a connection to the specified host, possibly due to network issues or incorrect URL.

fix

Verify the URL and network connectivity; consider implementing retries with exponential backoff for transient errors.

error ModuleNotFoundError: No module named 'aiohttp_retry' ↓

cause The `aiohttp-retry` library is not installed in your Python environment or the environment where your code is being executed.

fix

Install the library using pip: pip install aiohttp-retry

error TypeError: RetryClient.get() got an unexpected keyword argument 'retry_attempts' ↓

cause This error occurs when using an older API parameter (`retry_attempts`) with `aiohttp-retry` versions 2.0.0 and newer. The `retry_attempts` keyword argument was removed in version 2.0.0.

fix

Instead of retry_attempts, configure the number of attempts via RetryOptions and pass it to the RetryClient constructor or the request method. For example:

from aiohttp_retry import RetryClient, ExponentialRetry; retry_options = ExponentialRetry(attempts=3); retry_client = RetryClient(retry_options=retry_options)

or async with retry_client.get(url, retry_options=ExponentialRetry(attempts=3)).

Warnings

breaking Version 2.0 introduced backward incompatible changes. If upgrading from versions prior to 2.0 (e.g., v1.2), expect breaking changes in API usage. ↓

fix Review the official documentation and examples for versions 2.0+ to adapt your code. Consider `pip install aiohttp-retry==1.2` if you cannot upgrade.

breaking The `evaluate_response_callback` feature introduced a bug in versions 2.7.0 through 2.8.3 that could lead to infinite retries. These versions were yanked from PyPI. ↓

fix Upgrade to version 2.8.3 or higher (e.g., 2.9.1) to get the fix.

gotcha Since version 2.5.6, the `get_timeout` function in custom `RetryOptions` now receives an additional `response` parameter. If you have defined your own `RetryOptions` and custom `get_timeout` logic, it needs to be updated. ↓

fix Update your custom `get_timeout` signature to `def get_timeout(self, attempt_num: int, response: ClientResponse | None = None) -> float:`

gotcha When using `ExponentialRetry` or similar, setting `start_timeout` and `factor` to 0 will cause all retries to occur in quick succession without any delay, defeating the purpose of a backoff strategy. ↓

fix Ensure `start_timeout` and `factor` are set to appropriate non-zero values to introduce delays between retry attempts.

gotcha By default, `RetryClient` retries on all 5xx HTTP responses. If you want to specify custom 5xx errors or disable default 5xx retries, you must pass `retry_all_server_errors=False` in `RetryClient` constructor and explicitly define `statuses` in `RetryOptions`. ↓

fix To customize 5xx behavior: `RetryClient(retry_all_server_errors=False, retry_options=RetryOptions(statuses={500, 503}))`

breaking The `retry_attempts` keyword argument has been removed from `RetryClient` methods (including internal ones like `_request`) starting from version 2.0.0. If your code, particularly when interacting with `RetryClient` methods, attempts to pass this argument, it will result in a `TypeError`. ↓

fix Remove the `retry_attempts` keyword argument from any calls where it is being used. To specify the total number of attempts (including the initial request), configure it via `RetryOptions` by setting the `attempts` parameter (e.g., `RetryOptions(attempts=3)`).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.48s 27.2M

3.10 alpine (musl) - - 0.47s 27.5M

3.10 slim (glibc) wheel 4.5s 0.34s 29M

3.10 slim (glibc) - - 0.35s 30M

3.11 alpine (musl) wheel - 0.64s 29.8M

3.11 alpine (musl) - - 0.70s 30.1M

3.11 slim (glibc) wheel 3.8s 0.56s 32M

3.11 slim (glibc) - - 0.53s 33M

3.12 alpine (musl) wheel - 0.81s 21.6M

3.12 alpine (musl) - - 0.81s 22.0M

3.12 slim (glibc) wheel 2.9s 0.75s 24M

3.12 slim (glibc) - - 0.75s 25M

3.13 alpine (musl) wheel - 0.84s 21.0M

3.13 alpine (musl) - - 0.82s 21.3M

3.13 slim (glibc) wheel 3.1s 0.73s 23M

3.13 slim (glibc) - - 0.77s 24M

3.9 alpine (musl) wheel - 0.44s 27.4M

3.9 alpine (musl) - - 0.44s 27.4M

3.9 slim (glibc) wheel 5.4s 0.45s 30M

3.9 slim (glibc) - - 0.37s 30M

Imports

RetryClient
```
from aiohttp_retry import RetryClient
```

ExponentialRetry

from aiohttp_retry import ExponentialRetry

RandomRetry
```
from aiohttp_retry import RandomRetry
```
RetryOptions
```
from aiohttp_retry import RetryOptions
```
RequestParams
```
from aiohttp_retry import RequestParams
```

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to initialize a `RetryClient` with `ExponentialRetry` options and make a GET request. The `raise_for_status=False` parameter is often used to ensure that aiohttp-retry's retry logic can intercept and handle HTTP error responses instead of aiohttp immediately raising an exception. The example attempts to hit a 500 status endpoint, which should trigger the retry mechanism.

import asyncio
from aiohttp_retry import RetryClient, ExponentialRetry

async def main():
    # Configure retry options, e.g., 3 attempts with exponential backoff
    retry_options = ExponentialRetry(attempts=3, start_timeout=0.1, factor=2)

    # Create a RetryClient instance
    # raise_for_status=False prevents aiohttp from raising exceptions for HTTP error statuses,
    # allowing aiohttp-retry to handle them based on its retry logic.
    async with RetryClient(raise_for_status=False, retry_options=retry_options) as retry_client:
        try:
            # Make a GET request that will be retried on failure
            async with retry_client.get('https://httpbin.org/status/500', retry_attempts=3) as response:
                print(f"Final status: {response.status}")
                print(f"Content-type: {response.headers.get('Content-Type')}")
        except Exception as e:
            print(f"Request failed after retries: {e}")

if __name__ == '__main__':
    asyncio.run(main())