httpx Client middleware API (Fix)

The Fix

Upgrade to version 0.7.3 or later.

Based on closed encode/httpx issue #295 · PR/commit linked

Production note: Watch p95/p99 latency and retry volume; timeouts can turn into retry storms and duplicate side-effects.

Jump to Verify Open PR/Commit

@@ -1,38 +0,0 @@
@@ -1,38 +0,0 @@
-import typing
-from base64 import b64encode
-

repro.py

from httpx.base import AsyncDispatcher

class Middleware(AsyncDispatcher):
    def __init__(self, next_dispatcher, **kwargs):
        self.next_dispatcher = next_dispatcher

    async def send(
        self,
        request: AsyncRequest,
        verify: VerifyTypes = None,
        cert: CertTypes = None,
        timeout: TimeoutTypes = None,
    ) -> AsyncResponse:
        return await self.next_dispatcher.send(request, verify=verify, cert=cert, timeout=timeout)

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.7.3 or later.\nWhen NOT to use: This fix should not be used if the existing client functionality is required without middleware.\n\n

Why This Fix Works in Production

Trigger: timeout: TimeoutTypes = None,
Mechanism: Refactored client functionality into middleware to enhance extensibility of the Client and AsyncClient APIs
Why the fix works: Refactored client functionality into middleware to enhance extensibility of the Client and AsyncClient APIs. (first fixed release: 0.7.3).

Production impact:

If left unfixed, tail latency can spike under load and surface as timeouts/retries (amplifying incident impact).

Why This Breaks in Prod

Refactored client functionality into middleware to enhance extensibility of the Client and AsyncClient APIs
Production symptom (often without a traceback): timeout: TimeoutTypes = None,

Proof / Evidence

GitHub issue: #295
Fix PR: https://github.com/encode/httpx/pull/268
First fixed release: 0.7.3
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.75
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.66

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Pinging in here — anyone's got thoughts on this? Do we need the internal middleware at all? Is any of the proposed APIs potentially a…”

@florimondmanca · 2019-09-01 · source

“I'm good with #268 proceeding”

@sethmlarson · 2019-09-01 · source

“Great job on this @florimondmanca! I think #268 is a great first implementation of this, chances are we'll start noticing pain points as we start…”

@yeraydiazdiaz · 2019-09-02 · source

“Super @yeraydiazdiaz, I’m excited about Digest Auth!”

@florimondmanca · 2019-09-02 · source

Failure Signature (Search String)

timeout: TimeoutTypes = None,
return await self.next_dispatcher.send(request, verify=verify, cert=cert, timeout=timeout)

Copy-friendly signature

signature.txt

Failure Signature
-----------------
timeout: TimeoutTypes = None,
return await self.next_dispatcher.send(request, verify=verify, cert=cert, timeout=timeout)

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
timeout: TimeoutTypes = None,
return await self.next_dispatcher.send(request, verify=verify, cert=cert, timeout=timeout)

Minimal Reproduction

repro.py

from httpx.base import AsyncDispatcher

class Middleware(AsyncDispatcher):
    def __init__(self, next_dispatcher, **kwargs):
        self.next_dispatcher = next_dispatcher

    async def send(
        self,
        request: AsyncRequest,
        verify: VerifyTypes = None,
        cert: CertTypes = None,
        timeout: TimeoutTypes = None,
    ) -> AsyncResponse:
        return await self.next_dispatcher.send(request, verify=verify, cert=cert, timeout=timeout)

What Broke

Middleware implementation cluttered the BaseClient, impacting extensibility and maintainability.

Why It Broke

Refactored client functionality into middleware to enhance extensibility of the Client and AsyncClient APIs

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

Upgrade to version 0.7.3 or later.

When NOT to use: This fix should not be used if the existing client functionality is required without middleware.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/encode/httpx/pull/268

First fixed release: 0.7.3

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix should not be used if the existing client functionality is required without middleware.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
Upgrade behind a canary and run integration tests against the canary before 100% rollout.
Make timeouts explicit and test them (unit + integration) to avoid silent behavior changes.
Instrument retries (attempt count + reason) and alert on spikes to catch dependency slowdowns.

Version Compatibility Table

Version	Status
0.7.3	Fixed

Related Issues

No related fixes found.

Cluster: httpx:timeout All hubs All clusters

Related clusters: Configuration error Data consistency Other

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.