Spring Boot REST API Timeout Issue – Causes and Solutions

REST API timeout issues are one of the most common production problems in Spring Boot applications.

A request works fine locally but fails in production with:

• 504 Gateway Timeout

• 408 Request Timeout

• Connection timed out

• SocketTimeoutException

• Read timed out

In this article, we’ll explain:

• Why timeouts happen

• Where they occur (client, server, proxy)

• How to configure proper timeouts

• Best practices to prevent them

---

1️⃣ Where Does Timeout Actually Happen?

Timeout does not always mean your code is slow.

It can happen at:

1️⃣ Client (RestTemplate / WebClient)
2️⃣ Server (Tomcat)
3️⃣ Load Balancer (Nginx / Apache)
4️⃣ API Gateway
5️⃣ Database
6️⃣ External API call

You must first identify where the timeout originates.

---

2️⃣ Common Causes of Timeout

🔹 Slow Database Queries

• Missing indexes

• Large result sets

• Table locks

🔹 Blocking External API Calls

• Third-party API slow

• Network latency

🔹 Thread Pool Exhaustion

• Too many concurrent requests

• Blocking operations

🔹 Default Timeout Too Low

• RestTemplate default read timeout

• Proxy timeout mismatch

---

3️⃣ Fixing Client-Side Timeout (RestTemplate)

Default RestTemplate has no proper timeout configuration.

Configure like this:

@Bean
public RestTemplate restTemplate() {

    HttpComponentsClientHttpRequestFactory factory =
        new HttpComponentsClientHttpRequestFactory();

    factory.setConnectTimeout(5000);
    factory.setReadTimeout(5000);

    return new RestTemplate(factory);
}

---

4️⃣ Fixing WebClient Timeout

If using WebClient:

@Bean
public WebClient webClient() {
    HttpClient httpClient = HttpClient.create()
        .responseTimeout(Duration.ofSeconds(5));

    return WebClient.builder()
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .build();
}

---

5️⃣ Fixing Server-Side Timeout (Tomcat)

In application.yml:

server:
  connection-timeout: 5s
  tomcat:
    max-threads: 200
    accept-count: 100

---

6️⃣ Nginx / Reverse Proxy Timeout

Often 504 error comes from Nginx.

Example Nginx config:

proxy_connect_timeout 60s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;

If proxy timeout < backend processing time → 504.

---

7️⃣ Asynchronous Processing (Best Solution)

If API processing takes long time:

Instead of:

Client → Long Processing → Response

Use:

Client → Request Accepted (202)
Background Processing → Notify Later

Use:

• @Async

• Kafka

• Camunda workflow

• Message queue

This prevents blocking threads.

---

8️⃣ Database Optimization

• Add indexes

• Use pagination

• Avoid large JSON payload

• Avoid N+1 queries

• Monitor slow query logs

---

9️⃣ Thread Pool Tuning

If you see:

RejectedExecutionException

Tune:

server:
  tomcat:
    max-threads: 300
    min-spare-threads: 50

But increasing threads blindly is dangerous.
Always analyze CPU usage first.

---

🔟 Debugging Strategy

Step-by-step:

1. Check server logs

2. Check DB slow queries

3. Check proxy logs

4. Add response time logging

5. Use APM tools (New Relic, Prometheus, Grafana)

---

11️⃣ Production Best Practices

✔ Never block on long-running external calls
✔ Set both connect + read timeout
✔ Use circuit breakers (Resilience4j)
✔ Monitor API response time
✔ Use async/event-driven design

---

Conclusion

Timeout issues in Spring Boot REST APIs usually result from:

• Misconfigured timeouts

• Blocking operations

• Slow database queries

• Reverse proxy mismatch

Fixing timeout is not about increasing timeout blindly.
It is about identifying the bottleneck and designing scalable architecture.

💼 Need Help with Camunda, Jira, or Enterprise Workflows?

I help teams solve real production issues and build scalable systems.

Services I offer:

• Camunda & BPMN workflow design and debugging  

• Jira / Confluence setup and optimization  

• Java, Spring Boot & microservices architecture  

• Production issue troubleshooting  

🔗 View Services: https://shikhanirankari.blogspot.com/p/professional-services.html  

📩 Email: ishikhanirankari@gmail.com | info@realtechnologiesindia.com

🌐 IT Trainings | Digital metal podium

✔ Available for quick consulting calls and project-based support

✔ Response within 24 hours

🎥 Learn IT with Shikha on YouTube

Prefer learning through videos? Watch practical tutorials on Kafka, Camunda, Alfresco, Java, Spring Boot, Microservices and Enterprise Architecture.

▶ Subscribe to Learn IT with Shikha on YouTube