Mastering Request Timeouts in SpringBoot with @Timeout Annotation

Purpose of @Timeout Annotation

In Spring Boot applications each HTTP call often requires explicit configuration of connection and socket timeouts. Repeating this logic leads to verbose code and makes global timeout adjustments difficult. The @Timeout annotation centralises timeout handling: when applied to a controller or service method Spring automatically enforces the configured limit and returns a timeout error if execution exceeds the value.

Basic Usage

Annotate the target method with @Timeout and specify the timeout in milliseconds. Spring creates the underlying RequestConfig and applies it to the HTTP client, so no manual RestTemplate configuration is needed.

@Timeout(value = 5000) // 5‑second timeout
@GetMapping("/external")
public String callExternalService() {
    return externalService.getData();
}

If the method runs longer than 5 seconds Spring aborts the request and returns a 504 Gateway Timeout (or a custom error response defined by the application).

Advanced Usage – Fallback and Exception Handling

The annotation supports a fallbackMethod attribute. When a timeout occurs Spring invokes the fallback method, allowing the service to return a predefined response instead of propagating an exception.

@Timeout(value = 5000, fallbackMethod = "timeoutFallback")
@GetMapping("/external")
public String callExternalService() {
    return externalService.getData();
}

public String timeoutFallback(Throwable ex) {
    return "Request timed out, please try again later.";
}

The fallback method must have the same return type as the original method and can accept the triggering Throwable as a parameter.

Key Benefits

Simplified timeout control : No repetitive timeout configuration in each method.

Improved development efficiency : Developers focus on business logic; timeout details are handled declaratively.

Enhanced maintainability : Centralised timeout definition reduces duplication and eases global adjustments.

Flexible configuration : Custom timeout values, fallback methods, and exception handling are supported.

Real‑World Example

In a micro‑service API project multiple endpoints performed remote calls. Initially each call used a manually built RestTemplate with explicit setConnectTimeout and setSocketTimeout. After introducing @Timeout the codebase was reduced to a single annotation per endpoint:

@Timeout(value = 5000)
@GetMapping("/data")
public String getData() {
    return externalService.fetchData();
}

This change eliminated boilerplate, ensured consistent timeout behaviour across all services, and made future timeout adjustments a one‑line change in the annotation value.