Pythonpythonasyncaiohttpretryapi-clientproduction-ready
Async API Client with Retry
Production-ready async HTTP client using aiohttp with automatic retry, session management, and structured error handling.
import asyncio
import aiohttp
from typing import Any
from dataclasses import dataclass
@dataclass
class APIResponse:
status: int
data: Any
headers: dict
class AsyncAPIClient:
"""Production async API client with retry, timeout, and session management."""
def __init__(
self,
base_url: str,
timeout: int = 30,
max_retries: int = 3,
retry_delay: float = 1.0,
headers: dict | None = None,
):
self.base_url = base_url.rstrip("/")
self.timeout = aiohttp.ClientTimeout(total=timeout)
self.max_retries = max_retries
self.retry_delay = retry_delay
self.default_headers = headers or {}
self._session: aiohttp.ClientSession | None = None
async def __aenter__(self):
self._session = aiohttp.ClientSession(
timeout=self.timeout,
headers=self.default_headers,
)
return self
async def __aexit__(self, exc_type, exc_val, exc_tb):
if self._session:
await self._session.close()
self._session = None
async def _request(
self, method: str, path: str, **kwargs
) -> APIResponse:
if not self._session:
raise RuntimeError("Client not initialized. Use 'async with' context.")
url = f"{self.base_url}/{path.lstrip('/')}"
last_error: Exception | None = None
for attempt in range(self.max_retries):
try:
async with self._session.request(method, url, **kwargs) as resp:
data = await resp.json() if resp.content_type == "application/json" else await resp.text()
if resp.status >= 500:
raise aiohttp.ServerConnectionError(f"Server error: {resp.status}")
return APIResponse(
status=resp.status,
data=data,
headers=dict(resp.headers),
)
except (aiohttp.ClientError, asyncio.TimeoutError) as e:
last_error = e
if attempt < self.max_retries - 1:
delay = self.retry_delay * (2 ** attempt)
await asyncio.sleep(delay)
raise last_error or RuntimeError("Request failed after retries")
async def get(self, path: str, **kwargs) -> APIResponse:
return await self._request("GET", path, **kwargs)
async def post(self, path: str, **kwargs) -> APIResponse:
return await self._request("POST", path, **kwargs)
async def put(self, path: str, **kwargs) -> APIResponse:
return await self._request("PUT", path, **kwargs)
async def delete(self, path: str, **kwargs) -> APIResponse:
return await self._request("DELETE", path, **kwargs)title: "Async API Client with Retry" description: "Production-ready async HTTP client using aiohttp with automatic retry, session management, and structured error handling." category: "Python" language: "python" tags: ["python", "async", "aiohttp", "retry", "api-client", "production-ready"] createdAt: "2024-11-20" updatedAt: "2025-01-10"
Overview
A structured async HTTP client built on aiohttp that handles the common production concerns: automatic retries with exponential backoff, session lifecycle management via async context managers, configurable timeouts, and typed response objects.
The client retries only on server errors (5xx) and connection failures, not on client errors (4xx), which is the correct behavior for most API integrations.
Code
import asyncio
import aiohttp
from typing import Any
from dataclasses import dataclass
@dataclass
class APIResponse:
status: int
data: Any
headers: dict
class AsyncAPIClient:
"""Production async API client with retry, timeout, and session management."""
def __init__(
self,
base_url: str,
timeout: int = 30,
max_retries: int = 3,
retry_delay: float = 1.0,
headers: dict | None = None,
):
self.base_url = base_url.rstrip("/")
self.timeout = aiohttp.ClientTimeout(total=timeout)
self.max_retries = max_retries
self.retry_delay = retry_delay
self.default_headers = headers or {}
self._session: aiohttp.ClientSession | None = None
async def __aenter__(self):
self._session = aiohttp.ClientSession(
timeout=self.timeout,
headers=self.default_headers,
)
return self
async def __aexit__(self, exc_type, exc_val, exc_tb):
if self._session:
await self._session.close()
self._session = None
async def _request(self, method: str, path: str, **kwargs) -> APIResponse:
if not self._session:
raise RuntimeError("Client not initialized. Use 'async with' context.")
url = f"{self.base_url}/{path.lstrip('/')}"
last_error: Exception | None = None
for attempt in range(self.max_retries):
try:
async with self._session.request(method, url, **kwargs) as resp:
data = await resp.json() if resp.content_type == "application/json" else await resp.text()
if resp.status >= 500:
raise aiohttp.ServerConnectionError(f"Server error: {resp.status}")
return APIResponse(status=resp.status, data=data, headers=dict(resp.headers))
except (aiohttp.ClientError, asyncio.TimeoutError) as e:
last_error = e
if attempt < self.max_retries - 1:
delay = self.retry_delay * (2 ** attempt)
await asyncio.sleep(delay)
raise last_error or RuntimeError("Request failed after retries")
async def get(self, path: str, **kwargs) -> APIResponse:
return await self._request("GET", path, **kwargs)
async def post(self, path: str, **kwargs) -> APIResponse:
return await self._request("POST", path, **kwargs)Usage
import asyncio
from api_client import AsyncAPIClient
async def main():
async with AsyncAPIClient(
base_url="https://api.example.com/v1",
timeout=15,
max_retries=3,
headers={"Authorization": "Bearer YOUR_TOKEN"},
) as client:
# Simple GET
users = await client.get("/users")
print(f"Got {len(users.data)} users")
# Parallel requests
results = await asyncio.gather(
client.get("/users/1"),
client.get("/users/2"),
client.get("/users/3"),
)
for r in results:
print(f"User: {r.data['name']}")
if __name__ == "__main__":
asyncio.run(main())Notes
- Always use the
async withcontext manager to ensure proper session cleanup - The exponential backoff (
retry_delay * 2^attempt) prevents thundering herd issues - Server errors (5xx) trigger retries; client errors (4xx) do not, since retrying a bad request is pointless
- For production, add request/response logging with correlation IDs
- Consider adding a circuit breaker pattern for services that fail repeatedly
- The
aiohttp.ClientSessionreuses TCP connections internally, so creating one session per client lifetime is optimal