Circuit Breaker Pattern in Microservices

They complement each other. Retry handles a single dropped connection; the circuit breaker steps in when failures keep happening and stops the retries from making things worse.

• A timeout limits how long one call may wait. It does not remember previous calls.
• A bulkhead limits how many calls to one dependency can run at the same time, so it cannot use up all threads.
• A circuit breaker looks at recent history and stops calls entirely when a dependency keeps failing.

A timeout makes each failure quick, a bulkhead limits the damage, and the circuit breaker stops the repeated attempts. Production systems usually use all three together.

• COUNT_BASED judges the last N calls. It suits busy services with a steady flow of requests.
• TIME_BASED judges all calls from the last N seconds. It suits services with uneven traffic, because old results expire with time.

With a count-based window on a quiet service, a failure from an hour ago can still count against the service now. A time-based window avoids this:

slidingWindowType: TIME_BASED
slidingWindowSize: 60        # seconds
minimumNumberOfCalls: 10

Start from what normal looks like for that dependency, then pick values that only trigger on a real problem:

1. Check the normal error rate in your metrics. If it is usually 1–2%, a 50% threshold leaves plenty of room for normal noise.
2. Choose a window that sees enough calls to be meaningful, for example 20–100 calls for a busy service.
3. Set minimumNumberOfCalls so a handful of early failures cannot open the circuit.
4. Set waitDurationInOpenState to roughly how long the dependency usually needs to recover, often 10–60 seconds.

Then watch how the circuit behaves under real traffic and adjust. If it opens during normal operation, it is too sensitive; if it stays closed during outages, it is not sensitive enough.

Count errors that show the remote service is unhealthy, and ignore errors caused by the request:

Use recordExceptions and ignoreExceptions, or a recordFailurePredicate for more complex rules.

No. Resilience4j keeps the circuit state in memory, so each instance has its own breaker and decides independently.

This is usually fine and even desirable. Every instance sees the failures quickly and opens its own circuit within a few calls. It also means a network problem affecting only one instance does not block the others.

The trade-off is that each instance sends its own trial calls during half-open state. With many instances, keep permittedNumberOfCallsInHalfOpenState small so a recovering service is not flooded.

In the caller. The breaker protects the service that makes the call: it stops that service from wasting threads on a dependency that is failing. The failing service cannot protect its callers, because it may be too overloaded to respond at all.

For example, the Order Service wraps its call to the Payment Service. If the Inventory Service also calls the Payment Service, it has its own circuit breaker for that call.

Yes. Gateways such as Spring Cloud Gateway and service meshes such as Istio or Linkerd can apply circuit breaking to traffic between services without changing application code.

Many teams use both: the infrastructure provides a basic safety net for every service, and Resilience4j handles calls that need a smart fallback.

No. Hystrix has been in maintenance mode since 2018 and receives no new features. Spring Cloud also removed its Hystrix support.

Use Resilience4j for new projects. When migrating, the ideas map directly:

• Resilience4j directly (resilience4j-spring-boot3) gives you annotations, YAML configuration and every feature of the library. It is the simplest choice for most Spring Boot services.
• Spring Cloud CircuitBreaker is an abstraction layer with Resilience4j underneath. It offers a common programming API, and integrates with Spring Cloud Gateway and OpenFeign.

If you mainly protect method calls in your own code, use Resilience4j directly. If you use Spring Cloud Gateway or OpenFeign, the Spring Cloud starter connects them for you.

Check these common causes:

1. Not enough calls. The failure rate is only calculated after minimumNumberOfCalls calls. The default is 100.
2. The exception is caught inside the method, so the breaker only ever sees successes.
3. The exception is not recorded, because it is missing from recordExceptions or listed in ignoreExceptions.
4. The method is called from the same class, which skips the Spring proxy.
5. The AOP starter is missing, so the annotation has no effect.
6. The name does not match the instance in your configuration, so the default settings are used.

GET /actuator/circuitbreakerevents shows every recorded call, which quickly reveals whether failures are being counted.

The fallback signature must match exactly. Resilience4j looks for a method in the same class that has:

• The same return type as the protected method.
• The same parameters, in the same order.
• One extra exception parameter at the end, such as Throwable, Exception or a more specific type.

public PaymentResult charge(PaymentRequest request) { ... }

// Correct
private PaymentResult paymentFallback(PaymentRequest request, Throwable ex) { ... }

// Wrong: return type differs, so it is never used
private String paymentFallback(PaymentRequest request, Throwable ex) { ... }

Also check the exception type. A fallback declared with CallNotPermittedException only runs while the circuit is open, not when the call itself fails.

Be careful. If the fallback depends on another remote service, that service can fail too, and you are back where you started. Good fallbacks are local and fast: a cache, a default value, or saving the work for later.

If you must call a backup service, for example a second payment provider, protect that call with its own circuit breaker and a short timeout:

private PaymentResult paymentFallback(PaymentRequest request, Throwable ex) {
    return backupPaymentClient.charge(request); // has its own @CircuitBreaker
}

Yes, through the CircuitBreakerRegistry. This is useful during planned maintenance of a dependency, or to stop calls to a misbehaving partner immediately:

CircuitBreaker breaker = circuitBreakerRegistry.circuitBreaker("paymentService");

breaker.transitionToForcedOpenState(); // block all calls until told otherwise
breaker.transitionToDisabledState();   // let all calls through, no protection
breaker.transitionToClosedState();     // return to normal automatic behavior

Forced states do not change automatically, so remember to switch back. Expose such controls only through a secured admin endpoint.

Yes. Add the resilience4j-reactor module, and the same annotation works on methods returning Mono or Flux:

@CircuitBreaker(name = "inventoryService", fallbackMethod = "cachedStock")
public Mono<StockLevel> getStock(String sku) {
    return webClient.get()
            .uri("/api/stock/{sku}", sku)
            .retrieve()
            .bodyToMono(StockLevel.class);
}

private Mono<StockLevel> cachedStock(String sku, Throwable ex) {
    return Mono.justOrEmpty(stockCache.get(sku));
}

The fallback must return the same reactive type, Mono<StockLevel> here.

Yes. With Spring Cloud OpenFeign and the Spring Cloud CircuitBreaker Resilience4j starter, enable it with one property:

spring:
  cloud:
    openfeign:
      circuitbreaker:
        enabled: true

Then provide a fallback class that implements the Feign interface:

@FeignClient(name = "payment-service", fallback = PaymentClientFallback.class)
public interface PaymentFeignClient {

    @PostMapping("/api/payments")
    PaymentResult charge(@RequestBody PaymentRequest request);
}

@Component
class PaymentClientFallback implements PaymentFeignClient {

    @Override
    public PaymentResult charge(PaymentRequest request) {
        return PaymentResult.pending(request.orderId());
    }
}

Only the configured number of trial calls (permittedNumberOfCallsInHalfOpenState) are let through. Any other calls arriving at the same time are rejected with CallNotPermittedException, exactly as in the open state, so they go to the fallback.

Once the trial calls finish, the breaker calculates their failure rate. Below the threshold, it closes and all calls flow again. At or above it, it opens for another full wait period.

Subscribe to the circuit breaker’s events. This example logs every state change and sends an alert when a circuit opens:

@Component
public class CircuitBreakerAlerts {

    private static final Logger log = LoggerFactory.getLogger(CircuitBreakerAlerts.class);

    public CircuitBreakerAlerts(CircuitBreakerRegistry registry, AlertService alertService) {
        registry.getAllCircuitBreakers().forEach(breaker ->
                breaker.getEventPublisher().onStateTransition(event -> {
                    log.warn("Circuit {} changed: {}", event.getCircuitBreakerName(), event.getStateTransition());
                    if (event.getStateTransition().getToState() == CircuitBreaker.State.OPEN) {
                        alertService.notifyOnCall("Circuit OPEN: " + event.getCircuitBreakerName());
                    }
                }));
    }
}

In larger setups, alert on the resilience4j.circuitbreaker.state metric in your monitoring system instead, so alerts work the same way across all services.

Usually not for your primary database. If it is down, there is rarely a useful fallback, and the connection pool (HikariCP) already limits waiting through its own timeout settings.

Circuit breakers make sense around dependencies where a fallback does exist:

• A read-only reporting database or search engine, where you can show cached or partial results.
• A cache server such as Redis, where you can fall back to the main database.
• Third-party APIs, which you cannot control or fix.

Return 503 Service Unavailable, ideally with a Retry-After header that tells clients when to try again. This is clearer than a generic 500 error, because it says the problem is temporary:

@RestControllerAdvice
public class ResilienceExceptionHandler {

    @ExceptionHandler(CallNotPermittedException.class)
    public ResponseEntity<ProblemDetail> handleOpenCircuit(CallNotPermittedException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.SERVICE_UNAVAILABLE,
                "This feature is temporarily unavailable. Please try again shortly.");
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .header(HttpHeaders.RETRY_AFTER, "30")
                .body(problem);
    }
}

Avoid exposing internal details such as the name of the failing service in the response.