{"id":819,"library":"aiohttp-retry","title":"aiohttp-retry","description":"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.","status":"active","version":"2.9.1","language":"python","source_language":"en","source_url":"https://github.com/inyutin/aiohttp_retry","tags":["aiohttp","retry","async","asyncio","http-client","network"],"install":[{"cmd":"pip install aiohttp-retry","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"aiohttp-retry is a wrapper client built on top of aiohttp for handling retries.","package":"aiohttp"}],"imports":[{"symbol":"RetryClient","correct":"from aiohttp_retry import RetryClient"},{"symbol":"ExponentialRetry","correct":"from aiohttp_retry import ExponentialRetry"},{"symbol":"RandomRetry","correct":"from aiohttp_retry import RandomRetry"},{"symbol":"RetryOptions","correct":"from aiohttp_retry import RetryOptions"},{"symbol":"RequestParams","correct":"from aiohttp_retry import RequestParams"}],"quickstart":{"code":"import asyncio\nfrom aiohttp_retry import RetryClient, ExponentialRetry\n\nasync def main():\n    # Configure retry options, e.g., 3 attempts with exponential backoff\n    retry_options = ExponentialRetry(attempts=3, start_timeout=0.1, factor=2)\n\n    # Create a RetryClient instance\n    # raise_for_status=False prevents aiohttp from raising exceptions for HTTP error statuses,\n    # allowing aiohttp-retry to handle them based on its retry logic.\n    async with RetryClient(raise_for_status=False, retry_options=retry_options) as retry_client:\n        try:\n            # Make a GET request that will be retried on failure\n            async with retry_client.get('https://httpbin.org/status/500', retry_attempts=3) as response:\n                print(f\"Final status: {response.status}\")\n                print(f\"Content-type: {response.headers.get('Content-Type')}\")\n        except Exception as e:\n            print(f\"Request failed after retries: {e}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Upgrade to version 2.8.3 or higher (e.g., 2.9.1) to get the fix.","message":"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.","severity":"breaking","affected_versions":"2.7.0 - 2.8.3"},{"fix":"Update your custom `get_timeout` signature to `def get_timeout(self, attempt_num: int, response: ClientResponse | None = None) -> float:`","message":"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.","severity":"gotcha","affected_versions":">=2.5.6"},{"fix":"Ensure `start_timeout` and `factor` are set to appropriate non-zero values to introduce delays between retry attempts.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To customize 5xx behavior: `RetryClient(retry_all_server_errors=False, retry_options=RetryOptions(statuses={500, 503}))`","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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)`).","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-19T21:07:15.679Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure 'aiohttp' is installed in the correct environment by running 'python3.6 -m pip install aiohttp'.","cause":"The 'aiohttp' package is not installed or not accessible in the current Python environment.","error":"ModuleNotFoundError: No module named 'aiohttp'"},{"fix":"Implement error handling to manage unexpected content types and consider retrying the request upon failure.","cause":"The server responded with a non-JSON content type, causing a JSON decoding error.","error":"message='Attempt to decode JSON with unexpected mimetype: text/html; charset=utf-8'"},{"fix":"Verify the URL and network connectivity; consider implementing retries with exponential backoff for transient errors.","cause":"The client is unable to establish a connection to the specified host, possibly due to network issues or incorrect URL.","error":"ClientConnectorError: Cannot connect to host example.com:443 ssl:default [Connect call failed]"},{"fix":"Install the library using pip: `pip install aiohttp-retry`","cause":"The `aiohttp-retry` library is not installed in your Python environment or the environment where your code is being executed.","error":"ModuleNotFoundError: No module named 'aiohttp_retry'"},{"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))`.","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.","error":"TypeError: RetryClient.get() got an unexpected keyword argument 'retry_attempts'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.9.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/inyutin/aiohttp_retry","docs":null,"changelog":null,"pypi":"https://pypi.org/project/aiohttp-retry/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"install_checks":{"last_tested":"2026-05-19","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"2.9.1","pypi_latest":"2.9.1","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.47,"mem_mb":14.3,"disk_size":"27.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":14.3,"disk_size":"27.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.6,"import_time_s":0.33,"mem_mb":14.3,"disk_size":"29M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.35,"mem_mb":14.3,"disk_size":"30M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.64,"mem_mb":15.3,"disk_size":"29.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":15.3,"disk_size":"30.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3.8,"import_time_s":0.56,"mem_mb":15.3,"disk_size":"32M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":15.3,"disk_size":"33M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.8,"mem_mb":15.6,"disk_size":"21.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.81,"mem_mb":15.7,"disk_size":"22.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.9,"import_time_s":0.75,"mem_mb":15.6,"disk_size":"24M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.75,"mem_mb":15.7,"disk_size":"25M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.81,"mem_mb":15.8,"disk_size":"21.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.82,"mem_mb":15.8,"disk_size":"21.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":3,"import_time_s":0.74,"mem_mb":15.8,"disk_size":"23M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.77,"mem_mb":15.8,"disk_size":"24M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.43,"mem_mb":13.8,"disk_size":"27.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.44,"mem_mb":13.9,"disk_size":"27.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.3,"import_time_s":0.43,"mem_mb":13.8,"disk_size":"30M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"aiohttp-retry","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":13.9,"disk_size":"30M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]},"_links":{"self":"https://checklist.day/api/registry/aiohttp-retry","v1":"https://checklist.day/v1/registry/aiohttp-retry","v1_install":"https://checklist.day/v1/registry/aiohttp-retry/install","v1_imports":"https://checklist.day/v1/registry/aiohttp-retry/imports","v1_compatibility":"https://checklist.day/v1/registry/aiohttp-retry/compatibility","v1_quickstart":"https://checklist.day/v1/registry/aiohttp-retry/quickstart","docs":"https://checklist.day/docs"}}