Introduction

OkHttp lets you control several different timeout phases, and connection timeout is only one of them. If the goal is specifically "how long should the client wait while establishing the TCP connection," use connectTimeout. If the goal is broader request control, you may also need readTimeout, writeTimeout, or even callTimeout.

Set The Connection Timeout On The Client Builder

1import java.util.concurrent.TimeUnit;
2import okhttp3.OkHttpClient;
3
4OkHttpClient client = new OkHttpClient.Builder()
5    .connectTimeout(10, TimeUnit.SECONDS)
6    .build();

This tells OkHttp how long to wait while connecting to the remote host. If the connection cannot be established in that period, the call fails with a timeout-related IOException.

Other Timeouts Are Different

It is common to confuse the timeout types.

• 'connectTimeout limits connection establishment'
• 'readTimeout limits inactivity while reading the response'
• 'writeTimeout limits inactivity while sending the request body'
• 'callTimeout limits the entire call from start to finish'

A more complete client often looks like this:

1OkHttpClient client = new OkHttpClient.Builder()
2    .connectTimeout(10, TimeUnit.SECONDS)
3    .readTimeout(30, TimeUnit.SECONDS)
4    .writeTimeout(30, TimeUnit.SECONDS)
5    .callTimeout(45, TimeUnit.SECONDS)
6    .build();

That is often a better production configuration than tuning connection timeout alone.

Per-Call Customization Uses newBuilder()

If most requests should use one timeout but a specific call needs another, clone the base client.

OkHttpClient fastClient = client.newBuilder()
    .connectTimeout(3, TimeUnit.SECONDS)
    .build();

This is preferable to mutating shared global client state.

A Minimal Request Example

1import okhttp3.Request;
2import okhttp3.Response;
3
4Request request = new Request.Builder()
5    .url("https://example.com")
6    .build();
7
8try (Response response = client.newCall(request).execute()) {
9    System.out.println(response.code());
10} catch (java.io.IOException e) {
11    e.printStackTrace();
12}

If the remote host is slow to accept the connection, connectTimeout is the setting that governs how long this waits.

Pick Sensible Values

There is no universal correct timeout. Shorter values improve responsiveness on failures but can hurt users on slower or high-latency networks. Longer values reduce false timeouts but make failures feel slower.

The right value depends on:

• mobile versus server environment
• internal service call versus public internet call
• whether retries exist higher up the stack
• how much latency the user can tolerate

That is why timeout tuning is part of system behavior, not just syntax.

Android And Shared Clients

In Android apps, it is common to create one shared OkHttpClient and reuse it. Reusing the client is good because OkHttp manages connection pooling and internal resources efficiently. Setting the timeout once on a shared client is therefore the usual pattern.

Handling Timeouts Cleanly

Timeouts are normal failure modes, not exceptional in the "should never happen" sense. Your code should surface them clearly and decide whether to retry, show an error, or degrade gracefully.

For user-facing apps, a timeout should normally produce a message or retry path rather than a silent failure.

Common Pitfalls

The biggest mistake is changing connectTimeout when the real problem is a slow response body, which is governed by readTimeout instead. Another is using one overly aggressive timeout value for every environment. Developers also sometimes create a new OkHttpClient for every request, which defeats connection pooling benefits. Finally, catching generic Exception without distinguishing network timeout failures makes diagnostics harder than they need to be.

Summary

• Use connectTimeout to control how long OkHttp waits to establish a connection.
• Do not confuse it with read, write, or full-call timeouts.
• Configure timeouts on OkHttpClient.Builder.
• Use newBuilder() when one request class needs a different timeout profile.
• Pick timeout values based on network context and user experience, not just habit.