Documentation Python quickstart Blog Free tools Enterprise solutions hello@quanticdata.ioLog in

curl timeout: --max-time, --connect-timeout, retries and exit code 28

The two curl timeouts on one request timeline: --connect-timeout covers the connection to the server or proxy and stopped our test after 2007 ms, --max-time covers the whole request and stopped a slow response after 3005 ms; both end with exit code 28; the card lists the three messages curl printed.
The two curl timeouts on one request timeline: --connect-timeout covers the connection to the server or proxy and stopped our test after 2007 ms, --max-time covers the whole request and stopped a slow response after 3005 ms; both end with exit code 28; the card lists the three messages curl printed.

curl has two timeouts. --max-time 30 (short form -m 30) stops the whole request after 30 seconds, whatever it is doing. --connect-timeout 5 only limits the time to connect. Both accept decimals, and both end with exit code 28. Without them, curl waits as long as the network lets it.

We triggered every timeout below on purpose on 20 November 2026, with curl 8.22.0 on Windows 11, against httpbin.org (which can delay its answer), an address that never answers, and QuanticData proxies. All messages and timings are from those runs.

The two options side by side

OptionWhat it limitsOur testWhat curl printed
--max-time 3 / -m 3The whole operation: connect, send, wait, downloadA page that answers after 5 scurl: (28) Operation timed out after 3005 milliseconds with 0 bytes received
--connect-timeout 2Only the connection (name lookup, TCP, TLS)An address that never answerscurl: (28) Connection timed out after 2007 milliseconds
--connect-timeout 2.5Same, with a fractionSame addressConnection timed out after 2513 milliseconds
neitherNothingSame addressFailed to connect to 10.255.255.1:80 after 21027 ms: Could not connect to server
$ curl -sS --max-time 3 https://httpbin.org/delay/5 -o /dev/null; echo "exit=$?"
curl: (28) Operation timed out after 3005 milliseconds with 0 bytes received
exit=28

$ curl -sS --connect-timeout 2 http://10.255.255.1/ -o /dev/null; echo "exit=$?"
curl: (28) Connection timed out after 2007 milliseconds
exit=28

A request that finishes in time is not affected: -m 10 on a page that answers after 2 seconds returned 200 with time_total 2.48 s.

What happens with no timeout

Without either option, curl has no limit on the whole transfer. Against the address that never answers, our curl gave up after 21027 ms with "Failed to connect", still exit 28. That limit came from the operating system giving up on the TCP connection, not from a curl setting. A server that accepts the connection and then sends nothing, or sends one byte a minute, can hold a curl with no --max-time for much longer. In scripts and cron jobs, always set -m.

Retries after a timeout

$ curl -sS --max-time 2 --retry 2 --retry-delay 1 https://httpbin.org/delay/4 -o /dev/null; echo "exit=$?"
curl: (28) Operation timed out after 2006 milliseconds with 0 bytes received
curl: (28) Operation timed out after 2004 milliseconds with 0 bytes received
curl: (28) Operation timed out after 2000 milliseconds with 0 bytes received
exit=28
  • --retry N tries again after a timeout: one attempt plus two retries gave three lines above. --max-time applies to each attempt, not to the total.
  • --retry-max-time 4 caps the time spent retrying: with --retry 5 it stopped after two attempts.
  • Some HTTP errors are retried too. On a 503, curl printed "Warning: Problem : HTTP error. Retrying in 1 second. 2 retries left." (you only see it without -s).
  • --retry-all-errors with -f retries any failure: a 500 was tried twice, then curl exited 22.

On a site that limits requests per IP, more retries can make things worse; read 429 Too Many Requests before you raise the retry count.

Stalled downloads: --speed-limit and --speed-time

A transfer that started but slowed to a trickle does not trip --connect-timeout, and --max-time may be too long for a big file. --speed-limit and --speed-time abort when the speed stays below a floor:

$ curl -sS --speed-limit 100000 --speed-time 3 -o /dev/null "https://httpbin.org/drip?duration=8&numbytes=8&delay=0"
curl: (28) Operation too slow. Less than 100000 bytes/sec transferred the last 3 seconds

Timeouts through a proxy

Both options cover the proxy hop too. --connect-timeout 2 with a proxy address that does not answer stopped after 2002 ms, and -m 3 through Residential Basic on the 5-second page stopped after 3013 ms, exit 28 each time:

$ curl -sS --connect-timeout 2 -x http://10.255.255.1:8080 https://ipinfo.io/ip -o /dev/null; echo "exit=$?"
curl: (28) Connection timed out after 2002 milliseconds
exit=28

$ curl -sS -m 3 -x http://residentialboson.quanticdata.io:10000 -U "USER-...:PASS" https://httpbin.org/delay/5 -o /dev/null; echo "exit=$?"
curl: (28) Operation timed out after 3013 milliseconds with 0 bytes received
exit=28

Through a proxy, --connect-timeout measures the connection to the proxy gateway, not to the site, and --max-time still covers everything up to the last byte. To see where the time goes on your own requests, print curl's timers with -w:

curl -sS -m 20 -x http://residentialboson.quanticdata.io:10000 -U "USER-type-residential-country-us-session-to1-lifetime-30:PASS" -o /dev/null \
  -w "connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" https://ipinfo.io/ip
  • time_connect: the TCP connection to the gateway; this is what --connect-timeout limits.
  • time_appconnect: TLS with the site finished, through the tunnel.
  • time_starttransfer: the first byte of the answer.
  • time_total: everything; this is what --max-time limits.

Set --max-time from what your target sites need, with room to spare, and keep --connect-timeout short so a dead route fails fast.

Values that work, and setting them once

JobSuggested options
API call or page fetch in a script--connect-timeout 5 -m 30
Same, through a residential or mobile proxy--connect-timeout 5 -m 30
Large download--connect-timeout 10 --speed-limit 10000 --speed-time 30, no short -m
Health check that must answer fast--connect-timeout 2 -m 5

To avoid repeating them, put them in a config file and load it with -K; ours held connect-timeout = 5 and max-time = 30, and the request returned 200. In a shell script, check for exit 28 to tell a timeout apart from other failures.

Gateways and authentication are in how to use a proxy with curl, and the same ideas for wget are in wget with a proxy. Our residential proxies and mobile proxies take the same -x and -U options; there is a Residential Basic free trial.

Sources & further reading

FAQ

Quick answers on curl timeout.

Something else? Ask us

How do I set a timeout in curl?

Use --max-time SECONDS (or -m) to cap the whole request and --connect-timeout SECONDS to cap the connection. For example curl --connect-timeout 5 -m 30 URL. Both take decimals.

What is the difference between --max-time and --connect-timeout?

--connect-timeout only covers getting connected; once connected, the transfer can run on. --max-time covers everything, so a server that connects and then answers slowly is stopped only by --max-time: in our test, after 3005 ms on a page that took 5 s.

What is the default timeout in curl?

curl sets no limit on the whole transfer unless you pass -m. In our test with no options, the connection attempt to an address that never answers ended after 21027 ms, when Windows gave up on the TCP connection, still with exit code 28.

What does curl error 28 mean?

A timeout was reached: "Operation timed out" for --max-time, "Connection timed out" for --connect-timeout, "Operation too slow" for --speed-limit. Raise the limit, retry with --retry, or check that the host or proxy answers at all.

Does curl retry after a timeout?

Only with --retry N. With --max-time 2 --retry 2 curl made three attempts of about 2 seconds each. --retry-max-time limits the total time spent retrying.

Do curl timeouts work through a proxy?

Yes. --connect-timeout covers the connection to the proxy (2002 ms to a proxy address that did not answer) and --max-time covers the whole request through it (3013 ms through Residential Basic on a slow page).

Proxies for timed curl jobs

Residential and mobile proxies with country targeting and sticky sessions; set your timeouts and run.

Related reading