How to handle timeouts in cURL

Network latency, packet loss, or unresponsive endpoints can cause cURL requests to block far longer than expected, delaying automation and interactive work in terminals. Configuring explicit timeouts places predictable bounds on each call so background jobs, monitoring checks, and batch jobs remain responsive even when remote services misbehave.

The libcurl engine separates connection setup from data transfer and exposes dedicated timeout controls for each phase. Option --connect-timeout limits how long the TCP and optional TLS handshake may run before failing, while --max-time caps the total wall-clock duration from the start of the request until the last byte is received or the timeout is reached.

Timeout values must be tuned to match typical response times and network characteristics; limits set too low can interrupt legitimate slow responses, while overly generous limits fail to prevent hangs. When these options are combined with exit-status checks and logging in scripts, failures can be handled cleanly by triggering retries, switching endpoints, or alerting operators instead of leaving stuck processes behind.

1. Open a terminal session in the target environment where cURL is available on the command line.
2. Configure a connection timeout to limit how long the TCP and TLS handshake may run against an unreachable address.

   $ curl --connect-timeout 3 http://10.255.255.1/
   curl: (28) Failed to connect to 10.255.255.1 port 80: Connection timed out

   Option --connect-timeout accepts a floating-point value in seconds and returns exit status 28 when the handshake cannot complete within the configured limit.

3. Limit the total duration of a slow response using --max-time so that delayed endpoints cannot block scripts indefinitely.

   $ curl --max-time 3 https://httpbin.org/delay/10
   curl: (28) Operation timed out after 3001 milliseconds with 0 bytes received

   Setting --max-time below the normal response time for a service forces timeouts on valid traffic, while omitting it entirely allows individual calls to run for several minutes or longer under adverse network conditions.

4. Combine connection and total timeouts to protect both the handshake and transfer phases for API-style requests.

   $ curl --connect-timeout 2 --max-time 15 "https://www.example.com/api/health"
   HTTP/1.1 200 OK
   Content-Type: application/json
   Content-Length: 48
   
   {"status":"ok","uptime_seconds":123456}

   Using --connect-timeout alongside --max-time keeps failures predictable while still allowing healthy endpoints to respond within typical service-level objectives.

5. Inspect the exit status of a timed-out request to integrate error handling into automation or monitoring scripts.

   $ curl --connect-timeout 2 --max-time 5 http://10.255.255.1/
   curl: (28) Failed to connect to 10.255.255.1 port 80: Connection timed out
   $ echo $?
   28

   Exit status 28 specifically indicates a timeout in cURL, allowing shell scripts and higher-level tools to distinguish it from DNS failures, protocol errors, or HTTP status codes.

6. Verify that the configured limits behave as expected by measuring how quickly the command returns compared to the timeout values.

   $ time curl --connect-timeout 2 --max-time 5 http://10.255.255.1/
   curl: (28) Failed to connect to 10.255.255.1 port 80: Connection timed out
   
   real    0m2.01s
   user    0m0.00s
   sys     0m0.00s

   Successful configuration is indicated by prompt return to the shell within the chosen timeout window, consistent exit status 28 for forced timeouts, and the absence of long-running cURL processes when endpoints are unavailable.