Back in April I wrote a piece on this blog about timeout budgets and retry storms. The arithmetic there went like this: give every layer a slice of time, keep the lower layer's budget smaller than the one above it, otherwise retries pile onto each other. The arithmetic is right. But that article quietly assumed that the moment you write a budget into a client, the budget is actually enforced.
This week I tested that assumption and found it does not hold in most places.
I wrote an HTTP server that returns an eight-byte body, but sends those bytes three seconds apart. It has no ambition to be the world's slowest web server; its only job is to stall. Then I told the HTTP client of five languages, plus curl, the same thing: five seconds. Ten of them got a number; one I left untouched as a control — eleven setups in all. Seven of them waited twenty-four seconds and returned 200 as if nothing had happened.
The cause is not a bug but a difference in definition. In most clients, what we call a "timeout" is not a deadline placed on the total duration of a request; it is an hourglass set between two I/O events. Every byte that arrives turns it over again.
Machine, server and method
The measurements were taken on 13 November 2026 on my own machine: macOS (Darwin 25.6.0), Apple M4 Pro, everything over 127.0.0.1. Tool versions: curl 8.7.1, Python 3.9.6 with requests 2.32.3, Node.js 22.16.0, Go 1.26.1, OpenJDK 24, Ruby 2.6.10. The Python side ran through the absolute path /usr/bin/python3; my PATH also carries 3.13, and the exception class name differs between them — that is why the table below says socket.timeout. There is no network variable here — no packet loss, no DNS, no TLS handshake. What is left is only how the client keeps time.
The server is a seventy-line Python script. Its heart is this:
headers = (
"HTTP/1.1 200 OK\r\n"
f"Content-Length: {BODY_BYTES}\r\n"
"Content-Type: text/plain\r\n"
"Connection: close\r\n\r\n"
).encode()
conn.sendall(headers) # headers instantly
for i in range(BODY_BYTES): # body drop by drop
time.sleep(GAP)
conn.sendall(b"x")
I set up two scenarios:
- dripping: headers go out immediately, then eight bytes, each three seconds apart. Total delivery time 24 seconds.
- silent: the connection is accepted, not a single byte is sent, and the socket closes at the twentieth second. This is the control group for the question "does the timeout never work at all, or only fail against a drip?"
I wrote as honest a "five seconds" as I could into each client: whichever field the documentation points to for timeouts in that language. The one exception is Node's bare fetch: I deliberately left it alone, as a control for what the default does. The goal is not to pick a winner; it is to see how many different things the same sentence means across five languages and curl.
One limitation up front: every measurement is plaintext HTTP/1.1 over loopback. A TLS handshake, HTTP/2 flow control or a reverse proxy in between would change the table; these numbers show the behaviour underneath those layers.
Two scenes, the same five seconds
| Client and setting | silent server | dripping server |
|---|---|---|
curl --connect-timeout 5 |
20.01 s · exit 52 | 24.03 s · 200 · 8 B |
curl --max-time 5 |
5.01 s · exit 28 | 5.00 s · exit 28 · 1 B |
curl --speed-time 5 --speed-limit 1 |
5.00 s · exit 28 | 5.01 s · exit 28 · 1 B |
Python requests, timeout=5
|
5.01 s · ReadTimeout | 24.04 s · 200 · 8 B |
Python urllib, timeout=5
|
5.01 s · socket.timeout
|
24.04 s · 200 · 8 B |
Node fetch (no options) |
20.03 s · fetch failed | 24.05 s · 200 · 8 B |
Node fetch + AbortSignal.timeout(5000)
|
5.00 s · TimeoutError | 5.01 s · TimeoutError |
Go http.Client{Timeout: 5s}
|
5.00 s | 5.00 s (while reading the body) |
Go Transport{ResponseHeaderTimeout: 5s}
|
5.00 s | 24.04 s · 200 · 8 B |
Ruby Net::HTTP, read_timeout = 5
|
10.0 s · ReadTimeout | 24.03 s · 200 · 8 B |
Java HttpClient + .timeout(5s)
|
5.09 s · HttpTimeoutException | 24.19 s · 200 · 8 B |
The seven rows in bold are the ones that waited for all eight bytes and returned a successful result. Four rows cut the transfer at the fifth second. Against the silent server the table almost inverts: there, eight setups stand up at the fifth second, because there is no byte to reset the counter. Ruby wakes at the fifth second too, but pushes its total to ten for a reason we will come to shortly.
I repeated the timings three times and report the medians. The spread is surprisingly small: requests gave 24.04 · 24.04 · 24.03 across three runs; Java 24.19 · 24.17 · 24.19; Go 5.00 · 5.00 · 5.00. It should not be surprising, really — the server's delivery time is 8 × 3 seconds, so the number is entirely in my hands. What came out of the lab is not noise; it is a definition.
The most annoying row is the first. A curl command carrying --connect-timeout 5 will wait indefinitely once the connection is up; in the documentation's own words, that option "only limits the connection phase". That flag has been sitting in my scripts for years with the intent of "give up after five seconds". It does not give up.
Why it does not fire: who resets the counter
All seven rows share the same mechanism. The documentation does not hide it; we just do not read it.
Python requests splits the value in two: connect and read. For the read side the guide says the number is the seconds the client waits between bytes sent by the server, and adds in parentheses that "in 99.9% of cases, this is the time before the server sends the first byte". My server is precisely that 0.1%. As long as the three-second gaps stay under five seconds, the counter never fills. The same page also states separately that these values are not wall-clock.
urllib and the socket layer beneath it are even more bare: the settimeout docs define the value for "blocking socket operations", meaning every recv() gets its own five seconds. There is one interesting exception — sendall() has measured total duration since Python 3.5, and the docs say so explicitly. So in the very same library the sending side counts totals while the receiving side counts gaps. Two different clocks inside one language.
Node's fetch is built on undici, and both relevant undici options default to 300 seconds: headersTimeout and bodyTimeout. The body side documents itself: it "monitors the time between consecutive body chunks". Per chunk, in other words. A server dripping once every three seconds can keep that alive indefinitely. Node's own fetch documentation makes no mention of a default total limit; on the AbortSignal.timeout() side there is a single sentence: it returns a signal that will be aborted after the given milliseconds. In my measurements that signal was the one piece that actually worked.
Go is the only language here that names the header and body phases separately and gives each its own knob — requests documents a connect/read split too, but both of its halves count gaps. The comment on Transport.ResponseHeaderTimeout states that the time "does not include the time to read the response body". Because my server sends headers instantly, that setting never engages; the body trickles for 24 seconds and nobody objects. I read that comment not from the remote docs but from go doc net/http.Transport on my own machine — the same source as the Go version that ran the measurement.
Ruby's read_timeout is again per block read. But the 10 seconds it produced in the silent scenario gave away something else: Net::HTTP has a default max_retries of 1, so it retries an idempotent request once when it hits Net::ReadTimeout. The server log holds two separate GET /silent lines, five seconds apart. Running the same script with max_retries = 0 brought the time down to 5.01 seconds. So where I wrote five seconds, the library quietly spent ten — and that is the smallest, least charming version of the multiplication effect I described in my retry budget piece.
Java is the interesting case, because here the measurement fills a gap in the documentation. The HttpRequest.Builder.timeout() guide says an HttpTimeoutException is thrown if the response is not "received" within the given time, and adds a very clear sentence: not setting a timeout is the same as setting an infinite duration, i.e. blocking forever. Not a word about whether the body is covered. The measurement answers it: it is not. A request made with BodyHandlers.ofString() took 24.19 seconds and succeeded, despite its five-second timeout.
Third scene: the dripping byte is in the headers
Dripping the body is half the story. I played the same game with headers: a minimal 57-byte response header sent one byte per second, stretching header completion across 57 seconds.
| Client and setting | while headers drip |
|---|---|
curl --max-time 5 |
5.00 s · exit 28 · no status code |
Go Transport{ResponseHeaderTimeout: 5s}
|
5.01 s · "timeout awaiting response headers" |
Java HttpClient + .timeout(5s)
|
5.13 s · HttpTimeoutException |
Python requests, timeout=5
|
57.35 s · 200 · 8 B |
Node fetch (no options) |
57.39 s · 200 · 8 B |
Here Java's picture is complete: .timeout(5s) bounds the header phase as a total and does not bound the body at all. When the docs say "if the response is not received", they really do mean the headers; the body is not their concern. Go, meanwhile, named the two phases separately and gave each its own knob — the only language in the table that did. requests counts gaps here too: because the one-second gaps stayed under five, it never woke up for 57 seconds.
On the Node side this scene does not discriminate: undici's headersTimeout defaults to 300 seconds and my header drip lasted 57, so the measurement only shows that it stayed under 300. What the measurement cannot say, the documentation does: headersTimeout is the time the parser waits to receive the complete HTTP headers. Its sibling on the body side counts the gap between chunks; this one is a total for the header phase. Two settings side by side in one library, two different clocks — the same split we have been following all along.
The four that fired, and curl's small trap
Three of the four that cut the transfer make the same statement: they apply the number to the whole request. The fourth (--speed-time / --speed-limit) is a different mechanism altogether — not a deadline but a rate threshold; I take it apart in the next section.
curl --max-time says in its manual that it sets the maximum time you allow each transfer to take. Go's Client.Timeout comment is even clearer: the timeout includes connection time, any redirects, and reading the response body; the timer also keeps running after Get/Do return and will interrupt reading Response.Body. That is exactly what happened in the measurement: the error arrived while the body was being read. AbortSignal.timeout(5000) belongs to the same class — the signal cancels the request itself and does not care about the rhythm of the bytes.
There is a small but harmful detail here. Yes, curl --max-time 5 cuts the dripping transfer at the fifth second; but the %{http_code} output still reads 200, while %{size_download} is only 1 byte. If the exit code were not 28, my script would have counted that transfer as a success. Which means every shell line that decides success by looking at the status code will take a half-downloaded body for a complete one. The right question is not "what HTTP code?" but "what exit code, and did I get as many bytes as I expected?".
And there is an open-ended piece of arithmetic. One byte every three seconds means 1024 × 3 = 3072 seconds for a 1 KiB body, roughly 51 minutes. I did not measure that; I derived it from the rate in the table. But the size of the number tells you the point: as long as the gap counter never fills, the upper bound on total time depends on the server's patience, not on your setting.
The stall detector's threshold has to sit above the drip rate
curl also has a slow-transfer detector: --speed-limit and --speed-time. Per the manual, a transfer is aborted if it stays below speed-limit for a speed-time period. The defaults are defined in terms of each other: give only --speed-time and the limit is 1 byte per second; give only --speed-limit and the window is 30 seconds.
To show that this is a threshold, I sped the server up: 40 bytes, half a second apart, i.e. roughly 2 bytes per second.
--speed-time 5 --speed-limit 1 -> 20.14 s · 200 · 40 B · exit 0 (NO abort)
--speed-time 5 --speed-limit 5 -> 5.02 s · exit 28 · 9 B (abort)
The real rate in the first line is 40 ÷ 20.14 = 1.99 bytes per second. Since the limit was 1, the transfer counted as "fast enough" and flowed to the end. (curl's own %{speed_download} field rounds to an integer and prints 1B/s here; I computed the ratio from the raw numbers myself.) Raise the limit to 5 and the same server gets cut at the fifth second.
The practical takeaway: this detector is not a free safety net, it is a choice of threshold. Unless you write a number above the lowest rate you consider reasonable, the dripping side will sit just above your threshold and stall you as long as it likes.
Setting the total limit by hand: the patch that cuts at six seconds
Go and curl hand you a deadline out of the box. requests does not, so the deadline has to be hand-rolled: read the body as a stream and check the clock on every chunk.
with requests.get(url, timeout=5, stream=True) as r:
for chunk in r.iter_content(chunk_size=1):
chunks.append(chunk)
if time.monotonic() - t0 > TOTAL: # TOTAL = 5.0
raise TimeoutError("total deadline exceeded")
All three runs gave 6.02 · 6.01 · 6.02 seconds. Not five, six. The reason is a pleasant detail: the loop only wakes when a chunk arrives, and the bytes arrive at the third, sixth and ninth second. So a deadline at the fifth second is only noticed at the sixth.
That overshoot looks harmless but it scales: the excess equals the gap between bytes. Six seconds on a three-second drip; two minutes on a sixty-second drip. A deadline held inside the read loop is not an upper bound but an approximate upper bound. If you want a hard limit, it has to live outside the loop: either shrink the socket's own timeout to the remaining budget before every recv, or set a watchdog that kills the process from the outside. A real deadline is about whose hand the clock is in.
The same question on the server side: my own nginx
This article puts the client on the bench, but the question is symmetric: how long will my server hold a slow counterparty?
In this blog's nginx configuration, deploy/nginx-mustafaerbay-final.conf carries proxy_read_timeout 60s; in two places — which is nginx's default anyway. The documentation warns in the same entry: the timeout is set only between two successive read operations, not for the transmission of the whole response. So as long as my backend sends one byte every 59 seconds, the nginx worker waits there. The same sentence and the same 60-second default apply to proxy_send_timeout, send_timeout and client_body_timeout.
The exception sits one line away and it is valuable: client_header_timeout terminates the request with a 408 if the client does not transmit the entire request header within the given time. So nginx holds one example of each kind — one counts gaps, one counts the total. Saying "my timeouts are configured" without knowing which directive is which means putting the configured and the unconfigured into the same bag.
One more thing: client_header_timeout alone is not protection against a slow client. A thousand connections that each finish their header in 59 seconds stay inside the rule and can still fill the workers; the answer there is not a timeout but a cap on concurrent connections and request rate. My own file has one of the two: the /api/ location carries limit_req zone=mb_api burst=20 nodelay (10 requests per second) — but only there, and there is no limit_conn at all. So the root location that serves the pages is unprotected against the number of connections held open.
In the first version of this article I was going to close this section with "and here is how I fixed it". I did not fix it: 60 seconds is a reasonable ceiling for this blog, and the real gap is a layer that adds a total limit next to the gap-counting directive. I will not change it before measuring it.
Counting in my own code: 75 call sites, 52 with no limit
Measuring the outside world and skipping my own repository would have been the easy way out. I wrote a small script that scans the fetch( calls in this blog's code: it extracts each call's balanced parentheses and checks whether signal appears inside.
The result: 75 call sites, 23 with a signal, 52 without. The distribution is instructive too:
-
scripts/(the CI side, the code that talks to providers): 49 calls, 21 with a limit. -
src/(the app and the parts that run in the browser): 26 calls, only 2 with a limit.
The two groups do not carry the same risk. The ones under scripts/ go out to external providers and an agent waits on them during a CI run — one that hangs burns minutes. Most of the ones under src/ run in the browser against my own API; there, no deadline shows up as a spinner that never stops and the visitor reloads the page. The headline 52 sums both; the real bleeding is the 28 calls in the first group.
I should state the script's own limitation: it only looks for signal in the call text. If the codebase had a shared wrapper that added a deadline, this count would be wrong. There is none — every AbortSignal.timeout call in the repo is written directly into the fetch options, and there is no shared fetchWithTimeout helper. So 52 really does mean "this call has no deadline of its own".
Among the ones without a signal is this blog's own social-sharing step: the caption generation in scripts/social-post.ts calls fetch with no deadline for Gemini (line 467) and for the OpenAI-compatible providers (line 518). Elsewhere in the same file there are AbortSignal.timeout(5000) and AbortSignal.timeout(15000) calls — so the habit exists, the coverage does not. On top of that, .github/workflows/social-post.yml has no timeout-minutes line at all; for comparison, deploy-only.yml carries three separate limits of 50, 40 and 5 minutes. A dripping provider could keep that run busy, unnoticed, up to GitHub's own job ceiling.
This stays as open work, and I am writing it here so it does not get lost: the two calls on the caption path will get a deadline, and the workflow an outer limit. I did the counting for this article; I did not ship the fix with it.
Counting gaps is not always a defect
So far I have treated gap-counting settings as a defect; to be fair, sometimes they are exactly what you want. Put a hard total deadline on a client that listens to a server-sent event stream, or collects a language model's answer token by token, and you will cut off a long but healthy stream with your own hand; the right question there is not "how many seconds in total" but "how much silence between two chunks is acceptable". So bodyTimeout counting between chunks is not a flaw, it is the behaviour that job was designed for. The rule: if you expect a response with a known end (JSON, a file, an API call), set a total deadline; if you are listening to an open-ended stream, tighten the gap limit and bound the total from somewhere else.
Since I did not measure it, let me be explicit about the alarm side too: the signal that catches these hangs is not an error counter but a duration distribution. A request that takes 24 seconds and returns 200 shows up nowhere on an error graph; to see it you need a threshold on the request-duration histogram and on the bytes-per-second rate. My own pipeline has no such threshold; this measurement showed me that too.
A checklist: six questions before you accept a client
-
Does this setting count a gap or a total — and which phase? If the docs say "between", "successive" or "per chunk", it counts gaps. The phase is a separate question: Java's
.timeout()treats the header phase as a total and does not count the body at all. If there is no single total deadline, the client has no upper bound. -
Where does the total limit come from?
Client.Timeoutin Go,AbortSignal.timeoutin Node,--max-timein curl, a hand-built deadline in Python. If the library does not give you one, add it. -
Is the stall threshold above the lowest rate you expect? You will not catch a dripper with
--speed-limit 1; its rate may well be 2 bytes per second. -
What do retries multiply the budget by? Ruby's default
max_retries = 1turned five seconds into ten. If you usecurl --retry, the--max-timecounter restarts on every attempt;--retry-max-timeis what caps the total. - What are you measuring success by? The status code can read 200 while the body is incomplete. Check the exit code and the expected byte count too.
-
Which directive counts gaps on the server side? In nginx,
proxy_read_timeoutcounts gaps andclient_header_timeoutcounts the total. Trusting both equally is a mistake.
A timeout says who is allowed to be slow, and for how long
What I took away from the measurement is not a setting value but a shape of question. When we ask "how many seconds is the timeout?", we are conflating two separate things: how long the other side may stay completely quiet, and how long the whole job may take. Most libraries answer the first and leave the second to us — and they say so honestly in their documentation.
The gap between the two is invisible under normal conditions. The network either works or breaks; when it breaks, the counter fills, the error arrives, everyone feels safe. The gap only opens when the other side is slow but alive: a swollen queue, or a deliberate dripper. A seventy-line script sending one byte every three seconds held seven setups across five languages and curl for twenty-four seconds without sounding a single alarm. The same script could hold a CI run for hours — or take the slots in a connection pool one by one and close them to healthy requests.
The question to ask of your own setup is this: in this request, as long as the other side keeps sending me one byte per second, who decides when the job is over? If the answer is "nobody", what is missing is not a number of seconds — it is the clock itself.
Official Sources
- nginx — ngx_http_proxy_module (proxy_read_timeout)
- nginx — ngx_http_core_module (client_header_timeout, send_timeout)
- Go — net/http (Client.Timeout, Transport.ResponseHeaderTimeout)
- Python — socket (settimeout, timeout mode)
- undici — Client API (headersTimeout, bodyTimeout)
- curl — the --max-time option
- Node.js — globals (fetch, AbortSignal.timeout)
Top comments (0)