# curl Timeout: --max-time, --connect-timeout

> Set a timeout in curl: --max-time caps the whole request, --connect-timeout the connection. Real exit 28 messages, the default, retries and proxies.

[Home](https://quanticdata.io/) / [Blog](https://quanticdata.io/blog/) / curl Timeout: --max-time, --connect-timeout

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

Proxies · Nov 20, 2026 · 5 min read · By [Aldo Morese](https://quanticdata.io/about/), founder of QuanticData

![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.](https://quanticdata.io/blog/curl-timeout/hero.webp?v=20261120h)

On this page

- [The two options side by side](https://quanticdata.io/blog/curl-timeout/#the-two-options-side-by-side)
- [What happens with no timeout](https://quanticdata.io/blog/curl-timeout/#what-happens-with-no-timeout)
- [Retries after a timeout](https://quanticdata.io/blog/curl-timeout/#retries-after-a-timeout)
- [Stalled downloads: --speed-limit and --speed-time](https://quanticdata.io/blog/curl-timeout/#stalled-downloads-speed-limit-and-speed-time)
- [Timeouts through a proxy](https://quanticdata.io/blog/curl-timeout/#timeouts-through-a-proxy)
- [Values that work, and setting them once](https://quanticdata.io/blog/curl-timeout/#values-that-work-and-setting-them-once)

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.

**Run it on the free credit.** Every QuanticData account gets $2 of free API usage per month.

[Start free — $2/month included](https://quanticdata.io/signup/?utm_source=blog&utm_medium=website&utm_campaign=blog-lead&utm_content=curl-timeout) · [Explore Residential Proxies from $0.80/GB](https://quanticdata.io/residential-proxies/)

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

| Option | What it limits | Our test | What curl printed |
| --- | --- | --- | --- |
| `--max-time 3` / `-m 3` | The whole operation: connect, send, wait, download | A page that answers after 5 s | curl: (28) Operation timed out after 3005 milliseconds with 0 bytes received |
| `--connect-timeout 2` | Only the connection (name lookup, TCP, TLS) | An address that never answers | curl: (28) Connection timed out after 2007 milliseconds |
| `--connect-timeout 2.5` | Same, with a fraction | Same address | Connection timed out after 2513 milliseconds |
| neither | Nothing | Same address | Failed to connect to 10.255.255.1:80 after 21027 ms: Could not connect to server |

```bash
$ 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

```bash
$ 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](https://quanticdata.io/blog/429-too-many-requests-web-scraping/) before you raise the retry count.

**Try it on your own targets.** Every QuanticData account gets $2 of free API usage per month.

[Start free — $2/month included](https://quanticdata.io/signup/?utm_source=blog&utm_medium=website&utm_campaign=blog-inline&utm_content=curl-timeout) · [Explore Residential Proxies from $0.80/GB](https://quanticdata.io/residential-proxies/)

## 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:

```bash
$ 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:

```bash
$ 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`:

```bash
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

| Job | Suggested 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](https://quanticdata.io/blog/how-to-use-a-proxy-with-curl/), and the same ideas for wget are in [wget with a proxy](https://quanticdata.io/blog/wget-proxy-setup/). Our [residential proxies](https://quanticdata.io/residential-proxies/) and [mobile proxies](https://quanticdata.io/mobile-proxies/) take the same `-x` and `-U` options; there is a [Residential Basic free trial](https://quanticdata.io/residential-proxy-free-trial/).

### Sources & further reading

- [curl manual: -m, --max-time](https://curl.se/docs/manpage.html#-m)
- [curl manual: --connect-timeout](https://curl.se/docs/manpage.html#--connect-timeout)
- [curl manual: --retry](https://curl.se/docs/manpage.html#--retry)
- [curl manual: --speed-limit](https://curl.se/docs/manpage.html#-Y)
- [httpbin.org](https://httpbin.org/)

## FAQ

Quick answers on curl timeout.

[Something else? Ask us](mailto:hello@quanticdata.io)

### 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.

[Start free — $2/month included](https://quanticdata.io/signup/?utm_source=blog&utm_medium=website&utm_campaign=blog-end&utm_content=curl-timeout) · [Explore Residential Proxies from $0.80/GB](https://quanticdata.io/residential-proxies/)

## Related reading

- [curl Basic Auth: -u, Header, .netrc, Proxy](https://quanticdata.io/blog/curl-basic-auth/): Proxies · curl -u user:password sends HTTP basic authentication: curl base64-encodes the pair into an Authorization header. Below: the header we captured with -v, the same header built by hand, passwords with colons and @, the prompt, .netrc, digest, and why a proxy login goes in -U, not -u.
- [curl Download File: -O, -o, -L and Resume](https://quanticdata.io/blog/curl-download-file/): Proxies · curl -O URL saves the file under its remote name, curl -o name URL under the name you choose, and -L follows redirects such as GitHub's. Below: every option run for real, including the 0-byte file a 302 leaves behind, a resumed download that matched the original byte for byte, and 1 MB through residential and mobile proxies.
- [curl Show Response Headers and Send Headers](https://quanticdata.io/blog/curl-headers/): Proxies · curl -i prints the response headers with the body, -I only the headers (with a HEAD request), and -D - -o /dev/null the headers of a normal GET. To send headers, use -H "Name: value", once per header. Below: all of it run for real, plus a single header with -w, removing curl's defaults, headers from a file, and what a proxy sees.

---

Source: https://quanticdata.io/blog/curl-timeout/ · Site index for AI: https://quanticdata.io/llms.txt
