Introduction

ConnectionTimeout and SocketTimeout control two different phases of a network request. ConnectionTimeout limits how long the client waits to establish a TCP connection (the three-way handshake). SocketTimeout limits how long the client waits for data after the connection is already established. Setting them correctly is essential for building services that fail fast on unreachable hosts without dropping requests from slow-but-functioning servers.

Both throw similar exceptions (typically SocketTimeoutException in Java), which makes them easy to confuse. But they protect against completely different failure modes.

What Happens During a Network Request

A typical HTTP request goes through distinct phases, each with its own potential for delay:

11. DNS resolution      (resolve hostname to IP)
22. TCP connect          (three-way handshake: SYN, SYN-ACK, ACK)
33. TLS handshake        (if HTTPS)
44. Send request         (write HTTP headers and body)
55. Wait for response    (server processing time)
66. Read response        (receive HTTP headers and body)

ConnectionTimeout covers phase 2 (and sometimes phases 1 and 3 depending on the HTTP client). SocketTimeout covers phases 5 and 6, specifically the gap between receiving data packets.

ConnectionTimeout in Detail

ConnectionTimeout defines the maximum time to wait for the TCP connection to be established. If the remote server is unreachable, overloaded, or firewalled, the TCP handshake stalls and eventually times out.

Java HttpURLConnection

1URL url = new URL("https://api.example.com/data");
2HttpURLConnection conn = (HttpURLConnection) url.openConnection();
3conn.setConnectTimeout(3000);  // 3 seconds to establish connection
4conn.setReadTimeout(10000);    // 10 seconds to read response
5conn.connect();

Apache HttpClient 5

1RequestConfig config = RequestConfig.custom()
2    .setConnectTimeout(Timeout.ofSeconds(3))
3    .setResponseTimeout(Timeout.ofSeconds(10))
4    .build();
5
6CloseableHttpClient client = HttpClients.custom()
7    .setDefaultRequestConfig(config)
8    .build();

OkHttp (Kotlin/Java)

1val client = OkHttpClient.Builder()
2    .connectTimeout(3, TimeUnit.SECONDS)
3    .readTimeout(10, TimeUnit.SECONDS)
4    .writeTimeout(10, TimeUnit.SECONDS)
5    .build()

Python Requests

1import requests
2
3# (connect_timeout, read_timeout)
4response = requests.get(
5    "https://api.example.com/data",
6    timeout=(3, 10)  # 3s connect, 10s read
7)

When ConnectionTimeout Fires

A ConnectionTimeout typically indicates one of these problems:

• The server is down or not listening on that port.
• A firewall is silently dropping SYN packets (no RST returned).
• DNS resolved to a wrong or unreachable IP.
• The server's connection backlog is full and it cannot accept new connections.

A reasonable default is 3-5 seconds. If a TCP handshake takes longer than that, the server is likely unreachable and waiting longer rarely helps.

SocketTimeout in Detail

SocketTimeout (also called ReadTimeout in many libraries) defines the maximum time to wait between receiving consecutive data packets after the connection is established. It does not limit the total transfer time. It limits the idle gap.

Key Distinction: Per-Packet, Not Total

This is the most commonly misunderstood aspect. A SocketTimeout of 10 seconds does not mean the entire response must arrive within 10 seconds. It means that if 10 seconds pass without any new data arriving, the read operation times out.

A large response that streams continuously at 1 byte per second will never trigger a 10-second SocketTimeout. But a server that stops sending for 10 seconds will trigger it, even if it has already sent 99% of the response.

1// Server sends data in chunks with pauses
2// Chunk 1 at t=0s, Chunk 2 at t=3s, Chunk 3 at t=6s
3// SocketTimeout of 10s: succeeds (no gap > 10s)
4
5// Server sends Chunk 1 at t=0s, then pauses for 15s
6// SocketTimeout of 10s: fails at t=10s (gap > 10s)

When SocketTimeout Fires

A SocketTimeout after connection typically indicates:

• The server is processing the request and taking too long to respond.
• The server started sending a response but stalled mid-stream (garbage collection pause, deadlock, resource exhaustion).
• Network congestion is causing packet loss and retransmission delays.
• The server accepted the connection but is not reading or writing (connection leak on the server side).

Configuration Across Libraries

Note that some libraries (Go, Axios, cURL) use a total timeout rather than a per-phase timeout. A total timeout limits the entire request lifecycle, which is simpler to reason about but less precise.

Choosing the Right Values

General Guidelines

The Relationship Between Timeouts

ConnectionTimeout should almost always be shorter than SocketTimeout. The TCP handshake is a fixed, fast operation. If it takes more than a few seconds, waiting longer is pointless. But once connected, the server may legitimately need more time to process a complex query, compile a report, or stream a large dataset.

1// Good: fast connect, patient read
2config.setConnectTimeout(3000);
3config.setReadTimeout(30000);
4
5// Bad: patient connect, fast read
6config.setConnectTimeout(30000);  // Why wait 30s for a handshake?
7config.setReadTimeout(3000);      // Server barely has time to process

Retry Strategy and Timeout Interaction

Timeouts and retries interact in important ways. A ConnectionTimeout failure is usually safe to retry immediately on a different server instance (the request was never received). A SocketTimeout failure is more dangerous to retry because the server may have already started processing the request.

1import requests
2from requests.adapters import HTTPAdapter
3from urllib3.util.retry import Retry
4
5session = requests.Session()
6retry = Retry(
7    total=3,
8    backoff_factor=0.5,
9    status_forcelist=[502, 503, 504],
10    allowed_methods=["GET", "HEAD"],  # Only retry idempotent methods
11)
12adapter = HTTPAdapter(max_retries=retry)
13session.mount("https://", adapter)
14
15response = session.get(
16    "https://api.example.com/data",
17    timeout=(3, 10),
18)

For non-idempotent operations (POST, PUT), retrying after a SocketTimeout risks duplicate processing. Use idempotency keys or check the operation status before retrying.

Connection Pool Timeout

Many HTTP client libraries add a third timeout: the time to acquire a connection from the connection pool. This is separate from ConnectionTimeout (which is about TCP) and SocketTimeout (which is about data):

1// Apache HttpClient: connection pool timeout
2PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
3cm.setMaxTotal(100);
4cm.setDefaultMaxPerRoute(20);
5
6RequestConfig config = RequestConfig.custom()
7    .setConnectTimeout(Timeout.ofSeconds(3))
8    .setConnectionRequestTimeout(Timeout.ofSeconds(1))  // Pool wait
9    .setResponseTimeout(Timeout.ofSeconds(10))
10    .build();

If all connections in the pool are in use and a new request arrives, it waits up to connectionRequestTimeout for a connection to become available. This timeout firing usually means the pool is undersized or downstream services are slow.

Common Pitfalls

• Setting the same value for both timeouts. ConnectionTimeout should be much shorter than SocketTimeout. A 30-second connection timeout wastes time waiting for unreachable hosts.
• Using zero or no timeout. A missing timeout means the client will wait indefinitely. In a server handling concurrent requests, one stuck downstream call can exhaust the thread pool and cascade into a full outage.
• Confusing SocketTimeout with a total request timeout. SocketTimeout resets with every packet received. A slow but continuously streaming response will not trigger it, even if the total transfer takes minutes.
• Retrying non-idempotent requests after a SocketTimeout. The server may have already processed the request. The timeout only means the client did not receive the response, not that the server did not act on it.
• Ignoring connection pool timeout. Under load, requests may time out waiting for a connection from the pool, not waiting for the network. The symptoms look similar but the fix (increase pool size or reduce downstream latency) is different.
• Not logging which timeout fired. Both throw SocketTimeoutException in Java. Log the phase (connect vs. read) so you can distinguish "server unreachable" from "server too slow" in production.

Summary

• ConnectionTimeout limits the TCP handshake duration. Set it to 1-5 seconds. Failures indicate the server is unreachable.
• SocketTimeout limits the idle gap between data packets after connection. Set it based on expected server processing time. Failures indicate the server is slow or stalled.
• ConnectionTimeout should always be shorter than SocketTimeout.
• Never use zero or unlimited timeouts in production. Every outbound network call should have both timeouts configured.
• Retry ConnectionTimeout failures freely. Retry SocketTimeout failures only for idempotent operations.
• Log which timeout fired so you can distinguish network reachability problems from server performance problems.