{"id":2535,"library":"httpx-retries","title":"HTTPX Retries","description":"HTTPX Retries is a Python library that provides a comprehensive retry layer for HTTPX, addressing common issues with flaky and unreliable APIs. It offers an API surface similar to `urllib3.util.retry.Retry`, making it familiar for users migrating from `requests`. The library supports both synchronous and asynchronous HTTPX clients and is actively maintained with frequent releases.","status":"active","version":"0.4.6","language":"en","source_language":"en","source_url":"https://github.com/will-ockmore/httpx-retries","tags":["http client","retry","httpx","async","sync","network"],"install":[{"cmd":"pip install httpx-retries","lang":"bash","label":"Install httpx-retries"}],"dependencies":[{"reason":"Core HTTP client library for which retries are implemented. Version 0.4.1 relaxed the dependency to `>=0.20.0`.","package":"httpx","optional":false}],"imports":[{"symbol":"RetryTransport","correct":"from httpx_retries import RetryTransport"},{"symbol":"Retry","correct":"from httpx_retries import Retry"},{"note":"A similarly named, but abandoned, package `httpx-retry` (with a hyphen) exists, which uses `RetryPolicy` but is no longer maintained. Ensure you import from `httpx_retries` (with an underscore).","wrong":"from httpx_retry import RetryPolicy","symbol":"RetryPolicy","correct":"from httpx_retries import RetryPolicy"}],"quickstart":{"code":"import httpx\nfrom httpx_retries import RetryTransport, Retry\n\ndef sync_example():\n    # Basic usage with default retry strategy\n    with httpx.Client(transport=RetryTransport()) as client:\n        print(\"Sync Client (default retries):\")\n        try:\n            response = client.get(\"https://httpbin.org/status/503\")\n            print(f\"  Status: {response.status_code}\")\n        except httpx.HTTPStatusError as e:\n            print(f\"  Failed after retries: {e.response.status_code}\")\n\n    # Custom retry strategy\n    custom_retry = Retry(total=5, backoff_factor=0.5, statuses_forcelist=[503, 504])\n    with httpx.Client(transport=RetryTransport(retry=custom_retry)) as client:\n        print(\"\\nSync Client (custom retries):\")\n        try:\n            response = client.get(\"https://httpbin.org/status/503\")\n            print(f\"  Status: {response.status_code}\")\n        except httpx.HTTPStatusError as e:\n            print(f\"  Failed after retries: {e.response.status_code}\")\n\nasync def async_example():\n    # Async usage with default retry strategy\n    async with httpx.AsyncClient(transport=RetryTransport()) as client:\n        print(\"\\nAsync Client (default retries):\")\n        try:\n            response = await client.get(\"https://httpbin.org/status/503\")\n            print(f\"  Status: {response.status_code}\")\n        except httpx.HTTPStatusError as e:\n            print(f\"  Failed after retries: {e.response.status_code}\")\n\n    # Async usage with custom retry strategy\n    custom_retry = Retry(total=5, backoff_factor=0.5, statuses_forcelist=[503, 504])\n    async with httpx.AsyncClient(transport=RetryTransport(retry=custom_retry)) as client:\n        print(\"\\nAsync Client (custom retries):\")\n        try:\n            response = await client.get(\"https://httpbin.org/status/503\")\n            print(f\"  Status: {response.status_code}\")\n        except httpx.HTTPStatusError as e:\n            print(f\"  Failed after retries: {e.response.status_code}\")\n\nif __name__ == \"__main__\":\n    sync_example()\n    import asyncio\n    asyncio.run(async_example())\n","lang":"python","description":"This quickstart demonstrates both synchronous and asynchronous usage of `httpx-retries`. It shows how to apply the `RetryTransport` with its default retry strategy and how to configure a custom `Retry` strategy with parameters like `total` retries, `backoff_factor`, and `statuses_forcelist` to specify which HTTP status codes should trigger a retry. The example attempts to retrieve a 503 status, which will trigger the retry logic."},"warnings":[{"fix":"Use `httpx_retries.RetryTransport` with a configured `httpx_retries.Retry` object for status code-aware retries.","message":"HTTPX's built-in `HTTPTransport(retries=...)` only handles connection errors and timeouts, not retries based on HTTP status codes (e.g., 5xx server errors, 429 rate limits). If you need to retry requests based on specific HTTP response status codes, you must use `httpx-retries`.","severity":"gotcha","affected_versions":"All httpx versions"},{"fix":"Ensure you are installing `httpx-retries` (with an underscore) and importing `RetryTransport` and `Retry` from `httpx_retries`.","message":"There is a similarly named but abandoned package `httpx-retry` (with a hyphen) on PyPI. This package is no longer maintained and explicitly advises migration. Using the wrong package can lead to unmaintained code, security vulnerabilities, or unexpected behavior.","severity":"breaking","affected_versions":"All versions, due to package name similarity."},{"fix":"Upgrade to `httpx-retries` version `0.4.5` or later to ensure robust response closing during retry attempts, or explicitly manage response closing if using older versions.","message":"Prior to versions 0.4.4 and 0.4.5, `RetryTransport` might not have consistently closed all responses during retry operations, potentially leading to resource leaks, especially with server errors. This was particularly relevant for connections not managed by the client's context manager.","severity":"gotcha","affected_versions":"<0.4.5"},{"fix":"Update to `httpx-retries` version `0.3.2` or later to ensure correct handling of `Retry-After` headers, even when they specify a past time, reverting to default backoff when appropriate.","message":"In versions prior to 0.3.2, if a `Retry-After` header in a response specified a time in the past, the default backoff mechanism might not have been correctly applied, potentially leading to immediate and aggressive retries. This could overload target services.","severity":"gotcha","affected_versions":"<0.3.2"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}