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.

💼 Professional Support Available

If you are facing issues in real projects related to enterprise backend development or workflow automation, I provide paid consulting, production debugging, project support, and focused trainings.

Technologies covered include Java, Spring Boot, PL/SQL, CMS, Azure, and workflow automation (jBPM, Camunda BPM, RHPAM).

📧 Contact: ishikhanirankari@gmail.com | info@realtechnologiesindia.com

🌐 Website: IT Trainings | Digital metal podium