The Role of TimeLimiter in Resilience4j

For most Java developers, Spring Boot has become the industry standard for application development. It allows developers to prioritize core business logic by abstracting away complex dependency management and configuration.

As business requirements evolve, applications increasingly rely on multiple external APIs and services. If a downstream service experiences persistent failures, the application must be designed to handle these disruptions gracefully, preventing cascading failures and ensuring these critical interactions remain reliable.

1. Retry (Handling “Blips”)

• Purpose: To overcome transient (temporary) failures like a quick network glitch or a brief timeout.
• Scope: Localized to a single HTTP request.
• Behaviour: Re-executes the logic 2–3 times. If one attempt succeeds, the user never knows there was an issue.

2. Circuit Breaker (Handling “Outages”)

• Purpose: To manage persistent or systemic failures where a downstream service is completely down or overloaded.
• Scope: Global across multiple, independent HTTP requests.
• Behaviour: Monitors the failure rate across all users. If the service is consistently failing, it “trips” the circuit to stop all calls, preventing your application from wasting resources (threads/memory) on a dead service.

The Circuit Breaker pattern is an essential safeguard for building resilient systems. Implementation is straightforward, we simply need to add a single dependency to our project’s build file.

implementation("org.springframework.cloud:spring-cloud-starter-circuitbreaker-resilience4j:5.0.1")

Spring Boot provides Resilience4j as default implementation for the Circuit Breaker pattern. Spring Boot leverages Auto-Configuration to set up the Resilience4j framework, allowing you to start using resilience features immediately.

Inject/auto-wire

org.springframework.cloud.circuitbreaker.resilience4j.Resilience4JCircuitBreakerFactory

Create circuit-breaker instance

CircuitBreaker circuitBreaker = Resilience4JCircuitBreakerFactory.create("external-service-1");

Optional (if not, default configuration applies) : provide resilient4j configuration in application.yaml

resilience4j:
  circuitbreaker:
    instances:
      # circuit-breaker name
      external-service-1:
        failureRateThreshold: 50
        waitDurationInOpenState: 10000
        slidingWindowSize: 10

      Property             Default Value                   Value Description
waitDurationInOpenState         60s           Time to stay OPEN before checking service health.
failureRateThreshold            50%           Percentage of failures required to trip the circuit.
slidingWindowSize               100           Number of calls to monitor before calculating the rate.

While basic settings often suffice, the TimeLimiter is the most critical ‘under the hood’ configuration to manage. Without a precise timeout, a slow — but not technically ‘failed’ — external API can hang your threads and exhaust system resources.

By default, the TimeLimiter is set to 1000ms (1s). If a method execution exceeds this window, Resilience4j intercepts the call. While the top-level error might appear as a CallNotPermittedException (if the circuit is open), enabling TRACE logs reveals the root cause, TimeoutException.

So, always configure TimeLimiter based on your needs.

resilience4j:
  circuitbreaker:
    instances:
      # circuit-breaker name
      external-service-1:
        failureRateThreshold: 50
        waitDurationInOpenState: 10000
        slidingWindowSize: 10
  timelimiter:
    instances:
      # circuit-breaker name, same is applicable here as well
      external-service-1:
        # important configuration to consider        
        timeoutDuration: 5s