Introduction

“Request timeout” in a Spring Boot REST API can mean several different time limits. You need to distinguish between the servlet container waiting for request bytes, asynchronous request processing timing out, and outbound HTTP clients timing out while your controller calls another service.

Tomcat Connection Timeout Is Not Your Controller Runtime

A common Spring Boot property is server.tomcat.connection-timeout. Current Spring Boot docs describe it as the amount of time the connector waits, after accepting a connection, for the request URI line to be presented.

server:
  tomcat:
    connection-timeout: 20s

This helps with slow or stalled clients. It is not the setting that limits a normal synchronous controller method that takes a long time to execute.

Async Request Timeout in Spring MVC

If your controller returns Callable, DeferredResult, or a similar async type, Spring MVC has a separate timeout path. Spring Boot exposes spring.mvc.async.request-timeout for that case.

1spring:
2  mvc:
3    async:
4      request-timeout: 30s

You can also set a timeout per endpoint with WebAsyncTask.

1@GetMapping("/report")
2public WebAsyncTask<String> report() {
3    Callable<String> task = () -> {
4        Thread.sleep(5_000);
5        return "ready";
6    };
7    return new WebAsyncTask<>(10_000L, task);
8}

That is the right mechanism when your request processing is intentionally asynchronous.

Outbound Client Timeouts Matter Too

A Spring Boot API often times out because it is waiting on something else: another HTTP service, a database, or a message broker. In that case, the right timeout is on the client you are using.

For RestClient or WebClient, configure connect and read or response timeouts at the HTTP-client layer. A server timeout does not protect you from every slow dependency.

For example, a controller may respond quickly in isolation but still stall because an outbound HTTP call never returns. In that case, increasing servlet settings only hides the real issue. The dependency call needs its own bounded timeout and error handling strategy.

Prefer Fast Responses Over Large Timeouts

If an endpoint may run for minutes, increasing timeouts is usually the wrong fix. Better patterns are:

• move the work to a background job
• return 202 Accepted
• expose job status separately
• stream progress if the client truly needs an open connection

A REST endpoint that regularly blocks for a long time can tie up threads and degrade the whole service.

A Simple Timeout Example

For async MVC configuration, a Java config variant looks like this:

1import org.springframework.context.annotation.Configuration;
2import org.springframework.web.servlet.config.annotation.AsyncSupportConfigurer;
3import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
4
5@Configuration
6public class WebConfig implements WebMvcConfigurer {
7    @Override
8    public void configureAsyncSupport(AsyncSupportConfigurer configurer) {
9        configurer.setDefaultTimeout(30_000);
10    }
11}

That aligns with the Spring MVC async support documented by the Spring Framework reference.

If you are not using async controllers at all, and a request still feels like it is “timing out,” inspect the reverse proxy or load balancer in front of Spring Boot as well. Upstream infrastructure often has its own idle timeout.

Common Pitfalls

The first pitfall is assuming server.tomcat.connection-timeout limits the total execution time of every request. It does not.

Another mistake is raising timeouts without investigating the slow dependency that actually caused the delay.

A third issue is using synchronous long-running endpoints when a background job or async workflow would be more reliable.

Summary

• Spring Boot request timeouts are not one single setting.
• 'server.tomcat.connection-timeout is about socket and request-line waiting, not normal controller runtime.'
• 'spring.mvc.async.request-timeout applies to asynchronous Spring MVC request handling.'
• Downstream HTTP or database calls need their own client-side timeouts.
• Long-running work is often better modeled as an async job than a long-held HTTP request.