aiohttp-retry（aiohttp 重试）

aiohttp Retry Middleware

Add retry logic to aiohttp HTTP requests using the built-in client middleware system (ClientSession(middlewares=(...))) — no third-party libraries needed. Requires aiohttp 3.x+.

Announce at start: "I'm using the aiohttp-retry skill to implement retry middleware."

The Pattern

A factory function that returns a middleware. The middleware retries requests when the server responds with a transient status code.

import asyncio
import logging

from aiohttp import (
    ClientHandlerType,
    ClientMiddlewareType,
    ClientRequest,
    ClientResponse,
    ClientSession,
)

logger = logging.getLogger(__name__)

def retry_middleware(
    max_retries: int = 3,
    delay: float = 1.0,
    retryable_statuses: set[int] | None = None,
) -> ClientMiddlewareType:
    """Create a retry middleware for aiohttp ClientSession.

    Args:
        max_retries: Maximum number of attempts before giving up.
        delay: Seconds to wait between retry attempts.
        retryable_statuses: HTTP status codes that trigger a retry.
            Defaults to {429, 500, 502, 503, 504}.

    Returns:
        A middleware function compatible with ClientSession.
    """
    if retryable_statuses is None:
        retryable_statuses = {429, 500, 502, 503, 504}

    async def middleware(
        req: ClientRequest, handler: ClientHandlerType
    ) -> ClientResponse:
        last_resp: ClientResponse | None = None
        for attempt in range(1, max_retries + 1):
            resp = await handler(req)
            if resp.status not in retryable_statuses:
                return resp
            last_resp = resp
            if attempt < max_retries:
                logger.warning(
                    "Attempt %d/%d returned %d, retrying in %.1fs...",
                    attempt, max_retries, resp.status, delay,
                )
                await asyncio.sleep(delay)
        return last_resp

    return middleware

Usage

async with ClientSession(middlewares=(retry_middleware(max_retries=3, delay=1.0),)) as session:
    async with session.get("http://example.com/api/data") as resp:
        data = await resp.json()

Retries are transparent to the caller — every session.get(), session.post(), etc. goes through the middleware automatically.

Retryable Status Codes

Do not retry 4xx client errors (except 429) — those indicate a problem with the request itself.

Middleware Ordering

Middleware executes in the order listed. Order affects behavior:

# Logging runs per retry attempt (retry wraps logging):
ClientSession(middlewares=(retry_middleware(), logging_middleware))

# Logging runs once regardless of retries (logging wraps retry):
ClientSession(middlewares=(logging_middleware, retry_middleware()))

Place retry before middlewares that should run on each attempt (logging, metrics), and after middlewares that should run once (auth header injection).

Important: Request-Level Override

Passing middlewares to an individual request replaces session-level middlewares entirely (it does not extend them):

session = ClientSession(middlewares=(retry_middleware(),))

# Uses retry middleware
await session.get("http://example.com")

# Does NOT use retry middleware — only custom_mw runs
await session.get("http://example.com", middlewares=(custom_mw,))

# To keep both, pass both explicitly
await session.get("http://example.com", middlewares=(retry_middleware(), custom_mw))

Reference

• aiohttp Client Middleware docs
• aiohttp Middleware Cookbook