Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Overview

In this quick tutorial, we’ll focus on different types of timeouts we can set for the OkHttp client.

For the more general overview of the OkHttp library, check our introductory OkHttp guide.

2. Connect Timeout

A connect timeout defines a time period in which our client should establish a connection with a target host.

By default, for the OkHttpClient, this timeout is set to 10 seconds.

However, we can easily change its value using the OkHttpClient.Builder#connectTimeout method. A value of zero means no timeout at all.

Let’s now see how to build and use an OkHttpClient with a custom connection timeout:

@Test
public void whenConnectTimeoutExceeded_thenSocketTimeoutException() {
    OkHttpClient client = new OkHttpClient.Builder()
      .connectTimeout(10, TimeUnit.MILLISECONDS)
      .build();

    Request request = new Request.Builder()
      .url("http://203.0.113.1") // non routable address
      .build();

    Throwable thrown = catchThrowable(() -> client.newCall(request).execute());

    assertThat(thrown).isInstanceOf(SocketTimeoutException.class);
}

The above example shows that the client throws a SocketTimeoutException when the connection attempt exceeds the configured timeout.

3. Read Timeout

A read timeout is applied from the moment the connection between a client and a target host has been successfully established.

It defines a maximum time of inactivity between two data packets when waiting for the server’s response.

The default timeout of 10 seconds can be changed using OkHttpClient.Builder#readTimeout. Analogously as for the connect timeout, a zero value indicates no timeout.

Let’s now see how to configure a custom read timeout in practice:

@Test
public void whenReadTimeoutExceeded_thenSocketTimeoutException() {
    OkHttpClient client = new OkHttpClient.Builder()
      .readTimeout(10, TimeUnit.MILLISECONDS)
      .build();

    Request request = new Request.Builder()
      .url("https://httpbin.org/delay/2") // 2-second response time
      .build();

    Throwable thrown = catchThrowable(() -> client.newCall(request).execute());

    assertThat(thrown).isInstanceOf(SocketTimeoutException.class);
}

As we can see, the server doesn’t return the response within the defined timeout of 500 ms. As a result, the OkHttpClient throws a SocketTimeoutException.

4. Write Timeout

A write timeout defines a maximum time of inactivity between two data packets when sending the request to the server.

Similarly, as for the connect and read timeouts, we can override the default value of 10 seconds using OkHttpClient.Builder#writeTimeout. As a convention, a zero value means no timeout at all.

In the following example, we set a very short write timeout of 10 ms and post a 1 MB content to the server:

@Test
public void whenWriteTimeoutExceeded_thenSocketTimeoutException() {
    OkHttpClient client = new OkHttpClient.Builder()
      .writeTimeout(10, TimeUnit.MILLISECONDS)
      .build();

    Request request = new Request.Builder()
      .url("https://httpbin.org/delay/2")
      .post(RequestBody.create(MediaType.parse("text/plain"), create1MBString()))
      .build();

    Throwable thrown = catchThrowable(() -> client.newCall(request).execute());

    assertThat(thrown).isInstanceOf(SocketTimeoutException.class);
}

As we see, due to the large payload, our client isn’t able to send a request body to the server within the defined timeout. Consequently, the OkHttpClient throws a SocketTimeoutException.

5. Call Timeout

A call timeout is a bit different than the connect, read and write timeouts we already discussed.

It defines a time limit for a complete HTTP call. This includes resolving DNS, connecting, writing the request body, server processing, as well as reading the response body.

Unlike other timeouts, it’s default value is set to zero which implies no timeout. But of course, we can configure a custom value using OkHttpClient.Builder#callTimeout method.

Let’s see a practical usage example:

@Test
public void whenCallTimeoutExceeded_thenInterruptedIOException() {
    OkHttpClient client = new OkHttpClient.Builder()
      .callTimeout(1, TimeUnit.SECONDS)
      .build();

    Request request = new Request.Builder()
      .url("https://httpbin.org/delay/2")
      .build();

    Throwable thrown = catchThrowable(() -> client.newCall(request).execute());

    assertThat(thrown).isInstanceOf(InterruptedIOException.class);
}

As we can see, the call timeout is exceeded and the OkHttpClient throws an InterruptedIOException.

6. Per-Request Timeout

It’s recommended to create a single OkHttpClient instance and reuse it for all the HTTP calls across our application.

Sometimes, however, we know that a certain request takes more time than all the others. In this situation, we need to extend a given timeout only for that particular call.

In such cases, we can use an OkHttpClient#newBuilder method. This builds a new client that shares the same settings. We can then use the builder methods to adjust timeout settings as needed.

Let’s now see how to do this in practice:

@Test
public void whenPerRequestTimeoutExtended_thenResponseSuccess() throws IOException {
    OkHttpClient defaultClient = new OkHttpClient.Builder()
      .readTimeout(1, TimeUnit.SECONDS)
      .build();

    Request request = new Request.Builder()
      .url("https://httpbin.org/delay/2")
      .build();

    Throwable thrown = catchThrowable(() -> defaultClient.newCall(request).execute());

    assertThat(thrown).isInstanceOf(InterruptedIOException.class);

    OkHttpClient extendedTimeoutClient = defaultClient.newBuilder()
      .readTimeout(5, TimeUnit.SECONDS)
      .build();

    Response response = extendedTimeoutClient.newCall(request).execute();
    assertThat(response.code()).isEqualTo(200);
}

As we see the defaultClient failed to complete the HTTP call because of the exceeded read timeout.

That’s why we created the extendedTimeoutClient, adjusted the timeout value, and successfully executed the request.

7. Summary

In this article, we explored different timeouts we can configure for the OkHttpClient.

We also shortly described when the connect, read and write timeouts are applied during an HTTP call.

Additionally, we showed how easy it is to change a certain timeout value only for a single request.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW