Connection timeout vs read timeout: practical guidance for API calls

Short answer: connection timeout is how long the client waits to establish the TCP connection; read timeout is how long it waits for response data on an already open connection. In many HTTP clients you can configure both separately, and they protect different failure modes (HTTPX timeouts, Broadcom API Gateway timeouts).

Why the difference matters

Connection timeouts fail fast when a host is unreachable or too slow to complete the TCP handshake. Read timeouts guard the period after your request is sent, so a slow or stalled backend does not leave the client waiting indefinitely (HTTPX timeouts).

What each timeout actually controls

Connection timeout

• Scope: the socket connect phase (establishing the TCP connection).
• Behavior: if the socket cannot connect within the configured window, the client raises a connection timeout error (HTTPX timeouts).

Read timeout

• Scope: after the connection is established and the request is sent.
• Behavior: limits how long the client waits for a chunk of response data. Many clients measure this per received chunk, not as a single total response duration (HTTPX timeouts).
• Important nuance: this timer typically resets whenever data arrives. A server that trickles data can keep the connection alive indefinitely relative to the read-timeout value; you cannot force a hard overall cap on the request lifetime using a read timeout alone (Broadcom API Gateway timeouts).

Related timeouts you may also see

• Write timeout: how long the client waits to send a chunk of request data (relevant for large uploads) (HTTPX timeouts).
• Pool timeout: how long to wait for a free connection from the client’s pool (HTTPX timeouts).

Practical defaults and tuning tips

• Keep connection timeouts short to fail fast on reachability problems.
• Size read timeouts to the expected server processing and whether responses stream. For streaming, you often want a longer read timeout since regular chunks will keep it from firing (Broadcom API Gateway timeouts).
• Remember that some clients define read timeout as “time waiting for the next chunk,” not a total response limit (HTTPX timeouts).

Concrete example (HTTPX)

import httpx

# Separate connect/read timeouts. Also supports write and pool timeouts.
client = httpx.Client(timeout=httpx.Timeout(connect=3.0, read=15.0, write=10.0, pool=5.0))
resp = client.get("https://api.example.test/data")

In HTTPX, the default is to raise a timeout after 5 seconds of network inactivity if you do not configure timeouts explicitly (HTTPX timeouts).

Troubleshooting: identify which timeout fired

Signals that point to connection timeout

• Errors raised while opening the socket (for example, connect timeout exceptions).
• Often correlates with DNS issues, routing, firewall rules or a down host.

Signals that point to read timeout

• Request was sent successfully, then the client waited for the next response byte too long.
• Often correlates with slow application processing, upstream dependency slowness or large responses. Because read timers reset on data arrival, slow trickle responses may not trigger a read timeout (Broadcom API Gateway timeouts).

Safe retrying and operational considerations

• Use idempotent methods or idempotency keys when you retry after timeouts to avoid unintended duplicates.
• Align client timeouts with any API gateway or load balancer limits to avoid conflicting behavior.
• Log which timeout type fired (connect vs read) to route incidents to the right owner.

Quick checklist: verify your API timeout setup

• Set a short connection timeout so unreachable hosts fail fast.
• Set a read timeout that matches expected processing or streaming patterns.
• Confirm gateway/load balancer timeout policies and align with client settings.
• Log and surface the exact timeout type in errors and alerts.
• Test both cases: simulate unreachable host (connect) and slow server (read).
• Define retry rules and idempotency protections for timeout errors.

FAQs

Should connection timeout and read timeout use the same value?

No. Use a short connection timeout to detect reachability issues quickly, and choose a read timeout based on processing or streaming behavior so legitimate work is not cut off. Many clients measure read timeout per data chunk, not as a total cap (HTTPX timeouts, Broadcom API Gateway timeouts).

Does read timeout guarantee a maximum total request time?

No. Because the read timer typically resets on every received chunk of data, slow but steady responses can exceed the read-timeout value without triggering it (Broadcom API Gateway timeouts).

Related reading from Stack & Method: What is an API timeout? and Idempotency keys: safe retries without duplicate actions.