httpx.ReadTimeout: The read operation timed out

Python · updated 2026-11-03

Raised by httpx when a response does not arrive within the read timeout. The connection itself worked; the server was slow to answer. httpx defaults to 5 seconds, much shorter than many APIs (AI models, reports, exports) need.

Traceback (most recent call last):
  ...
  File "/app/.venv/lib/python3.12/site-packages/httpx/_transports/default.py", line 86, in map_httpcore_exceptions
    raise mapped_exc(message) from exc
httpx.ReadTimeout: The read operation timed out

Quick fix

Set a timeout that matches the call: httpx.Client(timeout=httpx.Timeout(30.0, connect=5.0)) for slow APIs, keeping a short connect timeout. Retry idempotent requests (GET) with backoff, and stream long responses instead of waiting for the whole body.

Check how long the endpoint normally takes; the 5 second default is often too short.
Configure the timeout on the client, not per call, so every request gets it.
Keep connect short and raise read for slow endpoints.
Retry idempotent calls with backoff; for POSTs, use an idempotency key if the API supports one.
For long jobs, ask the API for an async/job endpoint or stream the response.

python

import httpx

timeout = httpx.Timeout(30.0, connect=5.0)        # 30 s to read, 5 s to connect
client = httpx.Client(timeout=timeout, transport=httpx.HTTPTransport(retries=2))

try:
    r = client.get("https://api.example.com/reports/42")
    r.raise_for_status()
except httpx.ReadTimeout:
    log.warning("report 42 took longer than 30 s")
    raise

Why it happens

The default timeout is too short for the endpoint

httpx uses 5 seconds; report generation, AI completions and large exports routinely take longer, so they fail even though nothing is wrong.

The upstream service is slow or overloaded

Spikes on the other side, rate limiting that delays responses, or a cold start in a serverless API stretch response times past the limit.

Large responses read in one go

Downloading a big body without streaming counts the whole transfer against the read timeout between chunks on slow links.

A shared client with one timeout for everything

Fast and slow endpoints sharing a client with a short timeout make only the slow ones fail, which looks intermittent.

Other fixes

httpx.Timeout(None) disables timeouts; avoid it in production, since a stuck call then hangs a worker forever.
Libraries built on httpx (OpenAI and Anthropic SDKs, many API clients) accept a timeout and max_retries option.

Same error, other wording

httpx.ConnectTimeout: timed out
httpx.PoolTimeout
httpcore.ReadTimeout: The read operation timed out

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find the httpx ReadTimeout errors in production, group them by host and endpoint with their typical response times, and set per-client timeouts and retries that fit each one.

Plans from $29/mo See what your agent reads See the setupCancel any time from the billing portal