Setting a Request Timeout for a Spring REST API

1. Overview

In this tutorial, we’ll explore a few possible ways to implement request timeouts for a Spring REST API.

Then, we’ll discuss the benefits and drawbacks of each. Request timeouts are useful for preventing a poor user experience, especially if there’s an alternative that we can default to when a resource is taking too long. This design pattern is called the Circuit Breaker pattern, but we won’t elaborate more on that here.

2. @Transactional Timeouts

One way we can implement a request timeout on database calls is to take advantage of Spring’s @Transactional annotation. It has a timeout property that we can set. The default value for this property is -1, which is equivalent to not having any timeout at all. For external configuration of the timeout value, we must use a different property, timeoutString, instead.

For example, let’s assume we set this timeout to 30. If the execution time of the annotated method exceeds this number of seconds, an exception will be thrown. This might be useful for rolling back long-running database queries.

To see this in action, we’ll write a very simple JPA repository layer that will represent an external service that takes too long to complete and causes a timeout to occur. This JpaRepository extension has a time-costly method in it:

public interface BookRepository extends JpaRepository<Book, String> {

    default int wasteTime() {
        Stopwatch watch = Stopwatch.createStarted();

        // delay for 2 seconds
        while (watch.elapsed(SECONDS) < 2) {
          int i = Integer.MIN_VALUE;
          while (i < Integer.MAX_VALUE) {
              i++;
          }
        }
    }
}

If we invoke our wasteTime() method while inside a transaction with a timeout of 1 second, the timeout will elapse before the method finishes executing:

@GetMapping("/author/transactional")
@Transactional(timeout = 1)
public String getWithTransactionTimeout(@RequestParam String title) {
    bookRepository.wasteTime();
    return bookRepository.findById(title)
      .map(Book::getAuthor)
      .orElse("No book found for this title.");
}

Calling this endpoint results in a 500 HTTP error, which we can transform into a more meaningful response. It also requires very little setup to implement.

However, there are a few drawbacks to this timeout solution:

• Dependent on having a database with Spring-managed transactions
• Not globally applicable to a project since the annotation must be present on each method or class
• Doesn’t cut the request short when timeout is reached so the the entity still has to wait the full time processing

Let’s consider some alternate options.

3. Resilience4j TimeLimiter

Resilience4j is a library that primarily manages fault tolerance for remote communications. Its TimeLimiter module is what we’re interested in here.

First, we must include the resilience4j-timelimiter dependency in our project:

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-timelimiter</artifactId>
    <version>2.1.0</version>
</dependency>

Next, we’ll define a simple TimeLimiter that has a timeout duration of 500 milliseconds:

private TimeLimiter ourTimeLimiter = TimeLimiter.of(TimeLimiterConfig.custom()
  .timeoutDuration(Duration.ofMillis(500)).build());

We can easily configure this externally.

We can use our TimeLimiter to wrap the same logic that our @Transactional example used:

@GetMapping("/author/resilience4j")
public Callable<String> getWithResilience4jTimeLimiter(@RequestParam String title) {
    return TimeLimiter.decorateFutureSupplier(ourTimeLimiter, () ->
      CompletableFuture.supplyAsync(() -> {
        bookRepository.wasteTime();
        return bookRepository.findById(title)
          .map(Book::getAuthor)
          .orElse("No book found for this title.");
    }));
}

The TimeLimiter offers several benefits over the @Transactional solution. Namely, it supports sub-second precision and immediate notification of the timeout response. However, we still have to manually include it in all endpoints that require a timeout. It also requires some lengthy wrapping code, and the error it produces is still a generic 500 HTTP error. Finally, it requires returning a Callable<String> instead of a raw String.

The TimeLimiter comprises only a subset of features from Resilience4j, and interfaces nicely with a Circuit Breaker pattern.

4. Spring MVC request-timeout

Spring provides us with a property called spring.mvc.async.request-timeout. This property allows us to define a request timeout with millisecond precision.

Let’s define the property with a 750-millisecond timeout:

spring.mvc.async.request-timeout=750

This property is global and externally configurable, but like the TimeLimiter solution, it only applies to endpoints that return a Callable. Let’s define an endpoint that’s similar to the TimeLimiter example, but without needing to wrap the logic in Futures, or supplying a TimeLimiter:

@GetMapping("/author/mvc-request-timeout")
public Callable<String> getWithMvcRequestTimeout(@RequestParam String title) {
    return () -> {
        bookRepository.wasteTime();
        return bookRepository.findById(title)
          .map(Book::getAuthor)
          .orElse("No book found for this title.");
    };
}

We can see that the code is less verbose and that Spring automatically implements the configuration when we define the application property. Once the timeout has been reached, the response is returned immediately, and it even returns a more descriptive 503 HTTP error instead of a generic 500. Every endpoint in our project will inherit this timeout configuration automatically.

Now, let’s consider another option that will allow us to define timeouts with a little more granularity.

5. Configuring the Timeout in the HTTP Client

Rather than setting a timeout for an entire endpoint, we may want to simply have a timeout for a single external call. WebClient is Spring’s reactive web client that allows us to configure a response timeout.

Needless to say, all popular HTTP client libraries allow configuring custom timeouts for outgoing requests. For example, Spring’s older RestTemplate and WebClient’s non-reactive equivalent – the RestClient – both support this feature.

5.1. WebClient Timeout

To use WebClient, we must first add Spring’s WebFlux dependency to our project:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
    <version>2.4.2</version>
</dependency>

Let’s define a WebClient with a response timeout of 250 milliseconds that we can use to call ourselves via localhost in its base URL:

@Bean
public WebClient webClient() {
    return WebClient.builder()
      .baseUrl("http://localhost:8080")
      .clientConnector(new ReactorClientHttpConnector(
        HttpClient.create().responseTimeout(Duration.ofMillis(250))
      ))
      .build();
}

Clearly, we can easily configure this timeout value externally. We can also configure the base URL externally, as well as several other optional properties.

Now, we can inject our WebClient into our controller, and use it to call our own /transactional endpoint, which still has a timeout of 1 second. Since we configured our WebClient to timeout in 250 milliseconds, we should see it fail much faster than 1 second.

Here is our new endpoint:

@GetMapping("/author/webclient")
public String getWithWebClient(@RequestParam String title) {
    return webClient.get()
      .uri(uriBuilder -> uriBuilder
        .path("/author/transactional")
        .queryParam("title", title)
        .build())
      .retrieve()
      .bodyToMono(String.class)
      .block();
}

After calling this endpoint, we can see that we do receive the WebClient‘s timeout in the form of a 500 HTTP error response. We can also check the logs to see the downstream @Transactional timeout, but its timeout will be printed remotely if we call an external service instead of localhost.

Configuring different request timeouts for different backend services may be necessary, and is possible with this solution. Also, the Mono or Flux response that publishers returned by WebClient contains plenty of error handling methods for handling the generic timeout error response.

5.2. RestClient Timeout

Spring’s RestClient was introduced in Spring Framework 6 and Spring Boot 3 as a simpler, non-reactive alternative to WebClient. It offers a straightforward, synchronous approach while still providing a modern and fluent API design.

Firstly, let’s add the spring-boot-starter-web dependency if we don’t have it already:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Similarly to the previous example, we’ll start by creating a RestClient bean using the builder pattern:

@Bean
public RestClient restClient() {
    return RestClient.builder()
      .baseUrl("http://localhost:" + serverPort)
      .requestFactory(customRequestFactory())
      .build();
}

ClientHttpRequestFactory customRequestFactory() {
    ClientHttpRequestFactorySettings settings = ClientHttpRequestFactorySettings.DEFAULTS
      .withConnectTimeout(Duration.ofMillis(200))
      .withReadTimeout(Duration.ofMillis(200));
    return ClientHttpRequestFactories.get(settings);
}

As we can see, we can configure a default timeout value by defining a ClientHtttpRequestFactory inside the RestClient builder.

We can now use the HTTP client to make a request, and it will throw an exception if no response is received within the set threshold of 200 milliseconds:

@GetMapping("/author/restclient")
public String getWithRestClient(@RequestParam String title) {
    return restClient.get()
      .uri(uriBuilder -> uriBuilder
        .path("/author/transactional")
        .queryParam("title", title)
        .build())
      .retrieve()
      .body(String.class);
}

As we can see, the syntax is very similar to the reactive approach, allowing us to easily switch between the two without many code changes.

6. Conclusion

In this article, we explored several different solutions for implementing a request timeout. There are several factors to consider when deciding which one to use.

If we want to place a timeout on our database requests, we might want to use Spring’s @Transactional method and its timeout property. If we’re trying to integrate with a broader Circuit Breaker pattern, using Resilience4j’s TimeLimiter would make sense. Using the Spring MVC request-timeout property is best for setting a global timeout for all requests, but we can also easily define more granular timeouts per resource within an HTTP client such as WebClient and RestClient.