How to Fix Request Timeout in Spring Boot REST APIs (Production Guide)

Introduction

A request timeout is one of the most frustrating production issues in Spring Boot applications. Users click a button, wait for several seconds, and eventually receive an error instead of the expected response. Unlike an HTTP 500 Internal Server Error, where the application fails immediately, a timeout indicates that the server did not complete processing within the expected time.

Many developers assume increasing timeout values will solve the problem. In reality, timeouts are almost always symptoms of deeper issues such as slow database queries, blocked threads, external service delays, inefficient business logic, or resource exhaustion. Simply increasing timeout limits often hides the underlying bottleneck and allows the problem to grow worse.

In this guide, you’ll learn how request processing works in Spring Boot, understand the different types of timeouts, identify common production causes, and apply proven techniques to diagnose and resolve timeout issues effectively.

Prerequisites

Before reading this guide, you should understand:

• Java fundamentals
• Spring Boot basics
• REST APIs
• Spring MVC
• Spring Data JPA
• Database fundamentals

If you’re new to these topics, read these guides first:

• REST API Basics in Spring Boot (Production Ready Guide)
• Request Lifecycle in Spring Boot – From Client to Response
• Spring Boot REST API Slow Response (Performance Tuning Guide)
• How to Fix 500 Internal Server Error in Spring Boot
• How to Enable Debug Logging in Spring Boot for Production Issues

Learning Objectives

After reading this article, you’ll learn:

• What request timeouts are
• Different timeout types
• How Spring Boot processes requests
• Common production causes
• Database timeout troubleshooting
• External API timeout handling
• Thread pool tuning
• Monitoring techniques
• Production best practices

Table of Contents

1. Understanding Request Timeout
2. Spring Boot Request Lifecycle
3. Different Types of Timeouts
4. Common Causes
5. Database Timeouts
6. External Service Timeouts
7. Thread Pool Issues
8. Debugging Workflow
9. Production Best Practices
10. FAQs

What Is a Request Timeout?

A request timeout occurs when the server takes longer than the configured time limit to process an incoming request.

Example:

Client
   │
Waiting...
   │
Waiting...
   │
Waiting...
   │
Timeout

From the user’s perspective, the application appears unresponsive even though the server may still be processing the request in the background.

A timeout is typically caused by slow processing rather than an application crash.

Understanding the Complete Request Flow

Every HTTP request passes through several components before a response is returned.

Client
   │
Load Balancer
   │
API Gateway
   │
Embedded Tomcat
   │
DispatcherServlet
   │
Controller
   │
Service
   │
Repository
   │
Database
   │
External APIs (Optional)
   │
Response

A delay at any stage increases the overall response time.

For a detailed explanation of this flow, see Request Lifecycle in Spring Boot – From Client to Response.

Request Timeout vs Response Timeout

Many developers confuse these terms.

Timeout Type	Meaning
Request Timeout	Server takes too long to process the incoming request
Response Timeout	Client waits too long for the server’s response
Connection Timeout	Unable to establish a TCP connection
Read Timeout	Connected successfully but no response data arrives
Gateway Timeout	Reverse proxy or API Gateway timed out while waiting for the backend

Understanding which timeout occurred is the first step toward identifying the root cause.

Common Causes of Request Timeouts

The most common production causes include:

1. Slow SQL queries
2. Missing database indexes
3. Connection pool exhaustion
4. Long-running transactions
5. Blocking external API calls
6. Thread pool starvation
7. Large file uploads
8. Large response payloads
9. Infinite loops
10. Deadlocks
11. Excessive object serialization
12. Memory pressure
13. High CPU utilisation
14. Network latency
15. Misconfigured timeout values

Rather than increasing timeout limits, investigate these potential bottlenecks first.

1. Slow Database Queries

Database latency is one of the leading causes of request timeouts.

Example:

@GetMapping("/customers")
public List<Customer> customers(){

    return repository.findAll();

}

If findAll() retrieves millions of records, the request may exceed the configured timeout.

Symptoms

• Slow responses during peak traffic
• High database CPU utilisation
• Increased request latency
• Frequent timeout errors

How to Diagnose

Enable SQL logging temporarily:

logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE

Analyse query execution plans using:

• MySQL EXPLAIN
• PostgreSQL EXPLAIN ANALYZE
• Oracle Execution Plans
• SQL Server Query Execution Plans

Avoid tuning Spring Boot until you’ve confirmed the database isn’t the bottleneck.

2. Connection Pool Exhaustion

Spring Boot uses HikariCP by default.

If all database connections are busy, incoming requests wait for an available connection.

Typical log message:

HikariPool-1

Connection is not available

Request timed out after 30000ms

Common causes:

• Long-running transactions
• Connection leaks
• Slow SQL queries
• Pool size too small

Recommended configuration:

spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.datasource.hikari.connection-timeout=30000

Increase the pool size only after confirming that the database can handle additional concurrent connections.

3. Long-Running Database Transactions

A common production mistake is keeping database transactions open for much longer than necessary.

Consider the following example:

@Transactional
public void processOrder(Order order) {

    validate(order);

    paymentService.process(order);

    inventoryService.update(order);

    emailService.send(order);

}

Although only the inventory update requires database access, the transaction remains open while:

• Payment processing completes
• Inventory updates
• Email notifications are sent

This unnecessarily holds a database connection for the entire duration.

Why This Is a Problem

Every active transaction occupies a database connection.

With enough concurrent requests:

Request 1 → Connection #1 (Busy)
Request 2 → Connection #2 (Busy)
...
Request 20 → Connection #20 (Busy)
↓
New Request
↓
Waiting...
↓
Request Timeout

Best Practices

• Keep transactions as short as possible.
• Perform validation before opening a transaction.
• Move external API calls outside transactional boundaries.
• Avoid lengthy business logic inside @Transactional methods.

4. Blocking External REST API Calls

Most enterprise applications communicate with external services such as payment gateways, notification systems, or third-party APIs.

Example:

@GetMapping("/payment")
public PaymentResponse pay() {

    return paymentClient.processPayment();

}

If the payment provider takes 15 seconds to respond, your API also waits 15 seconds unless timeouts are configured correctly.

Common Symptoms

• API works locally but becomes slow in production.
• High response time despite low CPU usage.
• Random request timeouts.
• Increased thread utilisation.

Configure Timeouts

RestTemplate

@Bean
public RestTemplate restTemplate() {

    SimpleClientHttpRequestFactory factory =
            new SimpleClientHttpRequestFactory();

    factory.setConnectTimeout(3000);

    factory.setReadTimeout(5000);

    return new RestTemplate(factory);

}

This configuration ensures:

• Connection timeout: 3 seconds
• Read timeout: 5 seconds

Without these limits, requests may block indefinitely.

5. WebClient Timeout Configuration

If you’re using Spring WebFlux or WebClient, configure timeouts explicitly.

Example:

WebClient.builder()
    .clientConnector(
        new ReactorClientHttpConnector(
            HttpClient.create()
                .responseTimeout(Duration.ofSeconds(5))
        )
    )
    .build();

You should also implement:

• Retry
• Circuit Breaker
• Fallback responses

These patterns improve resilience when downstream services become slow or unavailable.

6. Thread Pool Starvation

Spring Boot processes incoming requests using a limited pool of server threads. If those threads remain occupied for too long, new requests must wait.

Typical causes include:

• Slow database queries
• Long-running business logic
• Blocking REST calls
• File generation
• Large report exports

Example:

@GetMapping("/report")
public Report generate() throws Exception {

    Thread.sleep(15000);

    return reportService.generate();

}

Each request now occupies a server thread for 15 seconds.

Under load, available threads are quickly exhausted.

Tomcat Configuration

server.tomcat.threads.max=200

Increasing this value is rarely the correct solution.

Always identify why threads remain busy before increasing thread counts.

7. File Upload Timeouts

Large file uploads frequently trigger timeout issues.

Example:

Client
↓
Upload 800 MB File
↓
Spring Boot
↓
Virus Scan
↓
Database Storage
↓
Timeout

Best Practices

• Validate file size.
• Use streaming uploads.
• Process large files asynchronously.
• Return upload progress where appropriate.
• Store files in object storage instead of the database.

8. Large Response Payloads

Large JSON responses require more time for:

• Database retrieval
• Serialization
• Network transfer
• Client parsing

Avoid:

return repository.findAll();

Use pagination:

Page<Customer> customers =
repository.findAll(PageRequest.of(0,20));

Also return DTOs instead of entire entity graphs.

This reduces:

• Memory usage
• Network traffic
• Serialization time
• Client rendering time

9. Tomcat Timeout Configuration

Tomcat provides several timeout-related settings.

Example:

server.tomcat.connection-timeout=20s

This defines how long Tomcat waits while establishing a connection.

Other important timeout settings may exist at:

• Load Balancer
• API Gateway
• Reverse Proxy
• Kubernetes Ingress

Increasing the timeout should be your last option after eliminating application bottlenecks.

10. Asynchronous Processing

Not every task should execute during the HTTP request.

Suppose sending an email takes 8 seconds.

Instead of:

userService.save(user);

emailService.send(user);

Use asynchronous processing.

@Async
public void sendEmail(User user){

}

Now the API can return immediately while the email is processed in the background.

Typical candidates for asynchronous execution:

• Email notifications
• SMS sending
• PDF generation
• Report exports
• Image processing
• Audit logging

Avoid using asynchronous execution for operations where the client must receive the result before the request completes.

11. API Gateway Timeout

Many production systems include an API Gateway between clients and Spring Boot services.

Client
    │
    ▼
API Gateway
    │
    ▼
Spring Boot

Even if Spring Boot continues processing the request, the gateway may stop waiting and return an error to the client.

Common gateway timeout responses include:

• HTTP 504 Gateway Timeout
• HTTP 408 Request Timeout

Verify timeout settings across all layers:

• API Gateway
• Load Balancer
• Reverse Proxy (Nginx/Apache)
• Spring Boot server
• Downstream services

The effective timeout is determined by the shortest limit in the request path.

Continuing directly from the previous section.

12. Monitoring Request Timeouts in Production

One of the biggest mistakes teams make is investigating timeouts after users report them. A production-ready Spring Boot application should continuously monitor request latency and alert the team before timeouts become widespread.

Spring Boot Actuator

Add the Actuator dependency:

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

Expose the required endpoints:

management.endpoints.web.exposure.include=health,metrics,prometheus,threaddump

Useful endpoints:

GET /actuator/health

GET /actuator/metrics

GET /actuator/prometheus

GET /actuator/threaddump

The most valuable metric is:

http.server.requests

This provides:

• Average response time
• Maximum response time
• Request count
• HTTP status codes
• 95th percentile latency
• 99th percentile latency

If your average response time is 200 ms but the 99th percentile is 12 seconds, a subset of requests is experiencing serious delays that require investigation.

13. Enable Micrometer with Prometheus and Grafana

For production environments, combine Spring Boot Actuator with Micrometer, Prometheus, and Grafana.

Spring Boot
↓
Micrometer
↓
Prometheus
↓
Grafana Dashboard

Recommended dashboards:

REST API Dashboard

Display:

• Average Response Time
• Maximum Response Time
• Requests Per Second
• HTTP 408 Count
• HTTP 500 Count
• HTTP 504 Count

JVM Dashboard

Monitor:

• Heap Usage
• Garbage Collection
• Thread Count
• CPU Usage
• Memory Allocation Rate

Database Dashboard

Track:

• Active Connections
• Idle Connections
• Connection Wait Time
• Slow Queries
• Transaction Duration

These dashboards allow you to detect performance degradation before customers experience failures.

14. Production Debugging Workflow

When a timeout occurs, avoid increasing timeout values immediately. Follow a structured investigation process.

                Request Timeout
                       │
        ┌──────────────┴──────────────┐
        │                             │
 Is Application Healthy?        No
        │
       Yes
        │
Check HTTP Response Time
        │
Slow Endpoint?
        │
Check SQL Queries
        │
Slow Database?
        │
Check Connection Pool
        │
External API?
        │
Thread Pool Busy?
        │
Memory Pressure?
        │
Network Latency?
        │
Fix Root Cause
        │
Re-Test

This workflow prevents unnecessary configuration changes and focuses on identifying the actual bottleneck.

Production Case Study 1 – Missing Database Index

Symptoms

A customer search API regularly timed out during office hours.

Users reported:

Request Timeout

after 30 seconds

Monitoring revealed:

• CPU Usage: 22%
• Memory Usage: Normal
• Database CPU: 96%

SQL query:

SELECT *
FROM customers
WHERE mobile_number = ?

Execution plan:

Full Table Scan

The mobile_number column had no index.

Solution

CREATE INDEX idx_customer_mobile
ON customers(mobile_number);

Results

Metric	Before	After
Average Response Time	11.4 s	82 ms
Database CPU	96%	41%
Timeout Errors	Frequent	Eliminated

Lesson: Always analyse the database before increasing application timeout settings.

Production Case Study 2 – External Payment Gateway Delay

Symptoms

The checkout API timed out intermittently.

Spring Boot logs showed no exceptions.

Application metrics:

• CPU: Normal
• Memory: Normal
• Database: Healthy

Investigation revealed the external payment provider occasionally took more than 20 seconds to respond.

Original Code

PaymentResponse response =
paymentClient.process(order);

No timeout configuration existed.

Solution

• Connection timeout: 3 seconds
• Read timeout: 5 seconds
• Retry policy for transient failures
• Circuit Breaker with fallback response

After deployment:

• Checkout completed faster.
• Thread utilisation decreased.
• Timeout errors dropped significantly.

Production Case Study 3 – Thread Pool Starvation

Symptoms

Every API became slow during month-end processing.

Monitoring showed:

• CPU: 35%
• Memory: Healthy
• Active Threads: Maximum

Investigation revealed a reporting endpoint generated large PDF reports synchronously.

Each request occupied a Tomcat thread for several minutes.

Solution

The report generation was moved to asynchronous processing.

Workflow:

Client
↓
Create Report Request
↓
Background Job
↓
Store Report
↓
Notify User
↓
Download Report

After implementation:

• Request latency improved dramatically.
• Thread pool utilisation returned to normal.
• No further timeout incidents occurred.

Common Mistakes

Mistake	Why It Causes Timeouts	Better Practice
Increasing timeout values without investigation	Hides the root cause	Measure and optimise first
Long-running @Transactional methods	Holds database connections	Keep transactions short
Calling external APIs synchronously	Blocks request threads	Configure timeouts and retries
Returning very large datasets	High serialization time	Use pagination and DTOs
Missing database indexes	Slow query execution	Optimise SQL and indexing
Ignoring Actuator metrics	Reactive troubleshooting	Continuous monitoring

Production Best Practices

• Set sensible connection and read timeouts for all outbound HTTP clients.
• Keep database transactions as short as possible.
• Optimise SQL queries before increasing timeout limits.
• Use pagination for large result sets.
• Process long-running tasks asynchronously.
• Monitor request latency using Actuator and Micrometer.
• Configure Circuit Breakers for external services.
• Review thread dumps during peak traffic.
• Load test before every production release.
• Set alerts for increasing response times and timeout rates.

Production Deployment Checklist

Before deploying a Spring Boot REST API:

• ✅ Database indexes reviewed.
• ✅ Slow queries analysed.
• ✅ HikariCP configured appropriately.
• ✅ HTTP client timeouts configured.
• ✅ Retry and Circuit Breaker implemented.
• ✅ Thread pool utilisation monitored.
• ✅ Actuator endpoints secured.
• ✅ Prometheus metrics enabled.
• ✅ Grafana dashboards configured.
• ✅ Load testing completed.
• ✅ Integration tests include timeout scenarios.

Interview Questions

1. What causes request timeouts in Spring Boot?

Common causes include slow database queries, long-running transactions, blocked threads, external service delays, connection pool exhaustion, and inefficient application logic.

2. Is increasing the timeout value the correct solution?

Not usually. Increasing timeout values treats the symptom rather than the root cause. Always identify and resolve the underlying bottleneck first.

3. What’s the difference between a connection timeout and a read timeout?

• Connection timeout: Maximum time allowed to establish a connection.
• Read timeout: Maximum time to wait for data after the connection has been established.

4. How do you monitor request latency in production?

Use Spring Boot Actuator with Micrometer, Prometheus, and Grafana to track request metrics, thread utilisation, JVM health, and database performance.

5. Why do long-running transactions cause timeouts?

They keep database connections occupied for longer, increasing wait times for other requests and potentially exhausting the connection pool.

Frequently Asked Questions

1. Why does my API work locally but time out in production?

Production environments have larger datasets, more concurrent users, external dependencies, and infrastructure limits that expose performance bottlenecks not visible during local development.

2. Can a slow database cause request timeouts?

Yes. Slow queries, missing indexes, table scans, and connection pool exhaustion are among the most common causes of request timeouts.

3. Should I increase server.tomcat.connection-timeout?

Only after confirming that the application is functioning correctly. Increasing timeout values without fixing the underlying issue often delays failures rather than preventing them.

4. How do asynchronous methods help prevent request timeouts?

They move long-running work—such as report generation or email sending—off the request thread, allowing the API to respond quickly while processing continues in the background.

Continue Reading on SpringBootFixes

Build a complete understanding of Spring Boot production troubleshooting with these related guides:

• Request Lifecycle in Spring Boot – From Client to Response
• Spring Boot REST API Slow Response (Performance Tuning Guide)
• How to Fix 500 Internal Server Error in Spring Boot
• How to Fix 404 Endpoint Not Found in Spring Boot
• Spring Boot Response Timeout – Causes & Fixes
• How to Enable Debug Logging in Spring Boot for Production Issues
• BeanCreationException in Spring Boot – Common Causes and Production Fixes
• Spring Boot Configuration Loading Order
• Dependency Injection in Spring Boot – Production Grade Explanation

Conclusion

Request timeouts are rarely solved by increasing timeout values alone. They are usually the result of deeper issues such as inefficient database queries, connection pool exhaustion, blocking external service calls, long-running transactions, thread starvation, or unoptimised application logic.

A systematic troubleshooting approach is essential. Start by measuring request latency with Spring Boot Actuator, analyse SQL performance, monitor JVM and thread utilisation, inspect external dependencies, and optimise the slowest part of the request lifecycle. Configure sensible timeout values, but treat them as safeguards—not substitutes for performance tuning.

By applying the techniques in this guide, you can build Spring Boot REST APIs that remain responsive, scalable, and reliable under real production workloads, reducing timeout errors and delivering a better experience for both users and operations teams.