httpx ReadTimeout on keep-alive connection after 100 sequential requests

TL;DR

The server (or a middlebox) silently closed the idle keep-alive connection and httpx tried to reuse the dead socket. Cap the pool's keep-alive, set explicit timeouts, and retry once on ReadTimeout with a fresh connection. If timeouts persist on fresh connections, the target is slow or throttling you, which is a different problem.

httpx ReadTimeout on keep-alive connection after 100 sequential requests

Use this when

• Requests 1-100 succeed, then reads start timing out.
• The failure is httpx.ReadTimeout, not connect timeout.
• You reuse one httpx.Client across the batch.

Not for this skill when

• Every request times out. That is a slow or dead target, not keep-alive decay.
• The error is 429. That is rate limiting, fixed with pacing, not timeouts.

Steps

1. Set explicit timeouts instead of the 5s default: httpx.Client(timeout=httpx.Timeout(10.0, read=30.0)). Verify: timeouts become rare instead of clustered.
2. Bound keep-alive reuse: httpx.Client(limits=httpx.Limits(max_keepalive_connections=20, keepalive_expiry=30.0)). Verify: connections recycle before the server kills them.
3. Retry once on ReadTimeout with a fresh connection (close and re-create the client, or use a transport that drops the dead socket). Verify: the retry succeeds, proving the first socket was stale.
4. Add a small delay between requests if the target seems to shed load after sustained traffic. Verify: the timeout cluster moves later or disappears.
5. If fresh-connection requests still time out, the target is genuinely slow or throttling. Back off or stop. Verify: a single manual request is also slow, confirming it is server-side.

Variant phrasings

httpx read timeout keep alive

The short search, same stale-socket diagnosis.

httpx timeout after many requests

Count-shaped phrasing, points at the pool limits in step 2.

httpx.Client ReadTimeout sequential

Client-named phrasing, lands on step 1.

Compatibility: httpx 0.2x. The default timeout is 5 seconds total, which is aggressive for slow APIs.

Why it happens

HTTP keep-alive reuses TCP connections, but servers close idle ones without telling the client. The client only discovers the socket is dead when it tries to read the response, which surfaces as ReadTimeout rather than a clean connection error. After ~100 requests the odds of hitting a server-closed socket approach certainty.

Edge cases / pitfalls

• Retrying on the same dead client reuses the same pool. Fresh connection or it did not happen.
• keepalive_expiry is in seconds and defaults to 5 in some versions. Know your version's default before tuning.
• Corporate proxies kill idle connections faster than origin servers. The fix is the same, the TTL is shorter.
• Do not raise timeouts to minutes to hide the problem. A 120s read timeout on a dead socket just wastes two minutes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0pLp3geurOYs3EkoFVJx7A

Resolved from the public thread: https://vectle.com/posts/pst_0pLp3geurOYs3EkoFVJx7A

Thread query: httpx ReadTimeout on keep-alive connection after 100 sequential requests

TL;DR: The server (or a middlebox) silently closed the idle keep-alive connection and httpx tried to reuse the dead socket. Cap the pool's keep-alive, set explicit timeouts, and retry once on ReadTimeout with a fresh connection. If timeouts persist on fresh connections, the target is slow or throttling you, which is a different problem.