Overview Learn how to make your microservice calls resilient using the Circuit Breaker pattern with Resilience4j and Spring Boot — complete demo, step-by-step commands, class-by-class explanations, sample outputs, real-world use cases, and production tips. Resilience4j Spring Boot Why This Matters Why This Matters In distributed systems, a failing downstream service can cascade and cause overall system outages. The Circuit Breaker pattern: Circuit Breaker Detects a failing dependency,
Stops sending requests to it (to avoid wasting resources),
Returns a graceful fallback response,
Periodically tests the dependency and restores normal operation when healthy. Detects a failing dependency, Stops sending requests to it (to avoid wasting resources), Returns a graceful fallback response, Periodically tests the dependency and restores normal operation when healthy. This reduces downtime, protects thread pools, keeps user experience reasonable, and prevents retry storms. Demo Summary (What You Have) Demo Summary (What You Have) A two-service Maven demo: hello-service (port 8081) — simple REST provider that intentionally fails intermittently. hello-service (port 8081) — simple REST provider that intentionally fails intermittently. hello-service (port 8081) — simple REST provider that intentionally fails intermittently. hello-service 8081 End point GET /api/hello GET /api/hello client-service (port 8080) — calls hello-service using RestTemplate and is protected by Resilience4j @CircuitBreaker with a fallback. client-service (port 8080) — calls hello-service using RestTemplate and is protected by Resilience4j @CircuitBreaker with a fallback. client-service (port 8080) — calls hello-service using RestTemplate and is protected by Resilience4j @CircuitBreaker with a fallback. client-service 8080 Resilience4j @CircuitBreaker End point GET /api/get-message GET /api/get-message Run both (hello-service and client-service) hello-service and client-service Then test GET http://localhost:8080/api/get-message GET http://localhost:8080/api/get-message Architecture Diagram This is a small, focused flow suitable for drawing a diagram Files & Code: Class-By-Class Explanation Files & Code: Class-By-Class Explanation hello-service hello-service HelloServiceApplication.java Standard @SpringBootApplication bootstrap class. Standard @SpringBootApplication bootstrap class. Standard @SpringBootApplication bootstrap class. @SpringBootApplication HelloController.java

@RestController
public class HelloController {

    private static int counter = 0;

    @GetMapping("/api/hello")
    public String sayHello() {
        counter++;
        // simulate intermittent failure: fail on every 3rd request
        if (counter % 3 == 0) {
            throw new RuntimeException("Simulated failure from Hello-Service!");
        }
        return "Hello from Hello-Service! (count=" + counter + ")";
    }
} HelloController.java

@RestController
public class HelloController {

    private static int counter = 0;

    @GetMapping("/api/hello")
    public String sayHello() {
        counter++;
        // simulate intermittent failure: fail on every 3rd request
        if (counter % 3 == 0) {
            throw new RuntimeException("Simulated failure from Hello-Service!");
        }
        return "Hello from Hello-Service! (count=" + counter + ")";
    }
} Explanation: This controller intentionally throws a RuntimeException on periodic calls to simulate transient failures you’d see in real systems (DB outage, bad data, timeouts). Explanation: client-service client-service ClientServiceApplication.java Standard Spring Boot main class. No special config required. Standard Spring Boot main class. No special config required. AppConfig.java
@Configuration
public class AppConfig {
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
} AppConfig.java
@Configuration
public class AppConfig {
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
} Explanation: Provides a single RestTemplate bean. Ensure RestTemplate is a Spring bean so AOP/resilience proxies can work properly. Explanation: HelloClientService.java
@Service
public class HelloClientService {

    private final RestTemplate restTemplate;

    @Value("${hello.service.url}")
    private String helloServiceUrl;

    public HelloClientService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    @CircuitBreaker(name = "helloService", fallbackMethod = "fallbackHello")
    public String getHelloMessage() {
        System.out.println("Calling hello service: " + helloServiceUrl);
        return restTemplate.getForObject(helloServiceUrl, String.class);
    }

    public String fallbackHello(Throwable t) {
        System.out.println("Fallback triggered: " + t);
        return "Hello Service is currently unavailable. Please try again later.";
    }
} HelloClientService.java
@Service
public class HelloClientService {

    private final RestTemplate restTemplate;

    @Value("${hello.service.url}")
    private String helloServiceUrl;

    public HelloClientService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }

    @CircuitBreaker(name = "helloService", fallbackMethod = "fallbackHello")
    public String getHelloMessage() {
        System.out.println("Calling hello service: " + helloServiceUrl);
        return restTemplate.getForObject(helloServiceUrl, String.class);
    }

    public String fallbackHello(Throwable t) {
        System.out.println("Fallback triggered: " + t);
        return "Hello Service is currently unavailable. Please try again later.";
    }
} Explanation (crucial bits) Explanation (crucial bits) @CircuitBreaker(name = "helloService", fallbackMethod = "fallbackHello") wraps the getHelloMessage() call in a circuit breaker. The name links to configuration properties.


fallbackHello(Throwable t) is called when the call fails according to the breaker rules.
The fallback must:
    o    Be in the same class

    o    Have the same return type

    o   Accept the original method parameters (none here) and a final Throwable parameter (or Exception/Throwable compatible with thrown exceptions)



Important: The method must be public, and the class must be a Spring bean (@Service), so proxy-based AOP works. @CircuitBreaker(name = "helloService", fallbackMethod = "fallbackHello") wraps the getHelloMessage() call in a circuit breaker. The name links to configuration properties. @CircuitBreaker(name = "helloService", fallbackMethod = "fallbackHello") wraps the getHelloMessage() call in a circuit breaker. The name links to configuration properties. fallbackHello(Throwable t) is called when the call fails according to the breaker rules.
The fallback must:
    o    Be in the same class

    o    Have the same return type

    o   Accept the original method parameters (none here) and a final Throwable parameter (or Exception/Throwable compatible with thrown exceptions) fallbackHello(Throwable t) is called when the call fails according to the breaker rules. The fallback must: The fallback must: o    Be in the same class

    o    Have the same return type

    o   Accept the original method parameters (none here) and a final Throwable parameter (or Exception/Throwable compatible with thrown exceptions) o    Be in the same class

    o    Have the same return type

    o   Accept the original method parameters (none here) and a final Throwable parameter (or Exception/Throwable compatible with thrown exceptions) Important: The method must be public, and the class must be a Spring bean (@Service), so proxy-based AOP works. Important: The method must be public, and the class must be a Spring bean (@Service), so proxy-based AOP works. ClientController.java
@RestController
public class ClientController {

    private final HelloClientService helloClientService;

    public ClientController(HelloClientService helloClientService) {
        this.helloClientService = helloClientService;
    }

    @GetMapping("/api/get-message")
    public String getMessage() {
        return helloClientService.getHelloMessage();
    }
} ClientController.java
@RestController
public class ClientController {

    private final HelloClientService helloClientService;

    public ClientController(HelloClientService helloClientService) {
        this.helloClientService = helloClientService;
    }

    @GetMapping("/api/get-message")
    public String getMessage() {
        return helloClientService.getHelloMessage();
    }
} Explanation: Simple controller delegating to HelloClientService. This ensures the call goes through the proxy where the circuit breaker is applied. Explanation: HelloClientService Configuration Used (client-service application.properties) Configuration Used (client-service application.properties) Key configuration used in the demo server.port=8080
spring.application.name=client-service

hello.service.url=http://localhost:8081/api/hello

resilience4j.circuitbreaker.instances.helloService.registerHealthIndicator=true
resilience4j.circuitbreaker.instances.helloService.slidingWindowSize=5
resilience4j.circuitbreaker.instances.helloService.minimumNumberOfCalls=2
resilience4j.circuitbreaker.instances.helloService.failureRateThreshold=50
resilience4j.circuitbreaker.instances.helloService.waitDurationInOpenState=10s

logging.level.io.github.resilience4j.circuitbreaker=DEBUG server.port=8080
spring.application.name=client-service

hello.service.url=http://localhost:8081/api/hello

resilience4j.circuitbreaker.instances.helloService.registerHealthIndicator=true
resilience4j.circuitbreaker.instances.helloService.slidingWindowSize=5
resilience4j.circuitbreaker.instances.helloService.minimumNumberOfCalls=2
resilience4j.circuitbreaker.instances.helloService.failureRateThreshold=50
resilience4j.circuitbreaker.instances.helloService.waitDurationInOpenState=10s

logging.level.io.github.resilience4j.circuitbreaker=DEBUG Meaning of important properties Meaning of important properties slidingWindowSize: number of calls the breaker monitors for failure percentage.
minimumNumberOfCalls: minimum calls before failure rate is evaluated.
failureRateThreshold: percent failures (e.g., 50) to open the circuit.
waitDurationInOpenState: how long the circuit stays open before moving to half-open.
registerHealthIndicator: exposes breaker state via actuator. slidingWindowSize: number of calls the breaker monitors for failure percentage. slidingWindowSize: minimumNumberOfCalls: minimum calls before failure rate is evaluated. minimumNumberOfCalls: failureRateThreshold: percent failures (e.g., 50) to open the circuit. failureRateThreshold: waitDurationInOpenState: how long the circuit stays open before moving to half-open. waitDurationInOpenState: registerHealthIndicator: exposes breaker state via actuator. registerHealthIndicator: Step-By-Step Run & Expected Outputs Start Services Start hello-service Start hello-service hello-service Visit: http://localhost:8081/api/hello Visit: http://localhost:8081/api/hello Returns → "Hello from Hello-Service!" (or throws simulated failure) Returns Start client-service Start client-service client-service Visit: http://localhost:8080/api/get-message Visit: http://localhost:8080/api/get-message Test Scenarios & Outputs Test Scenarios & Outputs Scenario A — Hello-Service Healthy Scenario A — Hello-Service Healthy Make a request GET http://localhost:8080/api/get-message GET http://localhost:8080/api/get-message Client logs Calling hello service: http://localhost:8081/api/hello
2025-11-13T11:58:23.366+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-8] i.g.r.c.i.CircuitBreakerStateMachine : CircuitBreaker 'helloService' succeeded:
2025-11-13T11:58:23.366+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-8] i.g.r.c.i.CircuitBreakerStateMachine : Event SUCCESS published: 2025-11-13T11:58:23.366634+05:30[Asia/Calcutta]: CircuitBreaker 'helloService' recorded a successful call. Elapsed time: 15 ms Calling hello service: http://localhost:8081/api/hello
2025-11-13T11:58:23.366+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-8] i.g.r.c.i.CircuitBreakerStateMachine : CircuitBreaker 'helloService' succeeded:
2025-11-13T11:58:23.366+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-8] i.g.r.c.i.CircuitBreakerStateMachine : Event SUCCESS published: 2025-11-13T11:58:23.366634+05:30[Asia/Calcutta]: CircuitBreaker 'helloService' recorded a successful call. Elapsed time: 15 ms Response Response Hello from Hello-Service! (count=4) Hello from Hello-Service! (count=4) Scenario B — Hello-Service Intermittent Failures Scenario B — Hello-Service Intermittent Failures If you call repeatedly and hello-service throws RuntimeException on some requests: RuntimeException ● Successful calls: client returns the hello message. ●  When a downstream call returns HTTP 500/exception: o    Resilience4j records the failure.

            o    If failure rate exceeds threshold (e.g., 50% over sliding window), the Circuit becomes **OPEN**.

            o    While OPEN, calls are short-circuited; **fallbackHello**() is immediately executed — no network call. \n                       **Client response while fallback active** o    Resilience4j records the failure.

            o    If failure rate exceeds threshold (e.g., 50% over sliding window), the Circuit becomes **OPEN**.

            o    While OPEN, calls are short-circuited; **fallbackHello**() is immediately executed — no network call. \n                       **Client response while fallback active** Client Response while active Client Response while active Response Response Hello Service is currently unavailable. Please try again later. Hello Service is currently unavailable. Please try again later. Sample client log sequence Sample client log sequence Calling hello service: http://localhost:8081/api/hello
2025-11-13T12:00:55.842+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-1] i.g.r.c.i.CircuitBreakerStateMachine : CircuitBreaker 'helloService' recorded an exception as failure: Calling hello service: http://localhost:8081/api/hello
2025-11-13T12:00:55.842+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-1] i.g.r.c.i.CircuitBreakerStateMachine : CircuitBreaker 'helloService' recorded an exception as failure: Scenario C — Recovery Scenario C — Recovery After waitDurationInOpenState (10s): waitDurationInOpenState waitDurationInOpenState (10s): Circuit goes to HALF_OPEN: a few test calls are allowed.
If test calls succeed, breaker CLOSES and normal traffic resumes.
If tests fail, the breaker goes back to OPEN. Circuit goes to HALF_OPEN: a few test calls are allowed. HALF_OPEN If test calls succeed, breaker CLOSES and normal traffic resumes. CLOSES If tests fail, the breaker goes back to OPEN. OPEN Real-World Use Cases Real-World Use Cases Payment Integration - A checkout service calling an external bank API: if the bank’s API becomes slow/fails, the circuit breaker returns a user-friendly message and prevents retry storms.
Third-party rate-limited APIs - APIs with limited calls per second — when limits are reached, the circuit opens to avoid hitting quotas further; fallback returns cached data.
Microservice chains inside an enterprise - Service A calls B, which calls C. If C is unstable, open breakers protect B and A, preventing system-wide slowdown.
Feature toggles and graceful degradation - When a non-critical feature service fails, return a simpler result to keep core functionality available (e.g., return product list without recommendations). Payment Integration - A checkout service calling an external bank API: if the bank’s API becomes slow/fails, the circuit breaker returns a user-friendly message and prevents retry storms. Payment Integration - Third-party rate-limited APIs - APIs with limited calls per second — when limits are reached, the circuit opens to avoid hitting quotas further; fallback returns cached data. Third-party rate-limited APIs - Microservice chains inside an enterprise - Service A calls B, which calls C. If C is unstable, open breakers protect B and A, preventing system-wide slowdown. Microservice chains inside an enterprise - Feature toggles and graceful degradation - When a non-critical feature service fails, return a simpler result to keep core functionality available (e.g., return product list without recommendations). Feature toggles and graceful degradation - Advantages & Business Value Advantages & Business Value Fault isolation — prevents one bad dependency from cascading.
Faster failure response — fails fast instead of waiting on timeouts.
Graceful degradation — offers fallback responses instead of full outages.
Resource protection — avoids wasting CPU, threads, and network.
Auto recovery — automatically returns to normal when the dependency is healthy.
Observability — breaker states and metrics can be exposed via the Actuator and monitored. Fault isolation — prevents one bad dependency from cascading. Fault isolation Faster failure response — fails fast instead of waiting on timeouts. Faster failure response Graceful degradation — offers fallback responses instead of full outages. Graceful degradation Resource protection — avoids wasting CPU, threads, and network. Resource protection Auto recovery — automatically returns to normal when the dependency is healthy. Auto recovery Observability — breaker states and metrics can be exposed via the Actuator and monitored. Observability Sample logs you’ll see (realistic) Sample logs you’ll see (realistic) Calling hello service: http://localhost:8081/api/hello
2025-11-13T12:00:55.842+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-1] i.g.r.c.i.CircuitBreakerStateMachine : CircuitBreaker 'helloService' recorded an exception as failure
2025-11-13T12:00:55.847+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-1] i.g.r.c.i.CircuitBreakerStateMachine : Event ERROR published: 2025-11-13T12:00:55.847908200+05:30[Asia/Calcutta]: CircuitBreaker 'helloService' recorded an error: 'org.springframework.web.client.HttpServerErrorException$InternalServerError: 500 : "{"timestamp":"2025-11-13T06:30:55.842+00:00","status":500,"error":"Internal Server Error","path":"/api/hello"}"'. Elapsed time: 8 ms
Fallback triggered: org.springframework.web.client.HttpServerErrorException$InternalServerError: 500 : "{"timestamp":"2025-11-13T06:30:55.842+00:00","status":500,"error":"Internal Server Error","path":"/api/hello"}" Calling hello service: http://localhost:8081/api/hello
2025-11-13T12:00:55.842+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-1] i.g.r.c.i.CircuitBreakerStateMachine : CircuitBreaker 'helloService' recorded an exception as failure
2025-11-13T12:00:55.847+05:30 DEBUG 32692 --- [client-service] [nio-8080-exec-1] i.g.r.c.i.CircuitBreakerStateMachine : Event ERROR published: 2025-11-13T12:00:55.847908200+05:30[Asia/Calcutta]: CircuitBreaker 'helloService' recorded an error: 'org.springframework.web.client.HttpServerErrorException$InternalServerError: 500 : "{"timestamp":"2025-11-13T06:30:55.842+00:00","status":500,"error":"Internal Server Error","path":"/api/hello"}"'. Elapsed time: 8 ms
Fallback triggered: org.springframework.web.client.HttpServerErrorException$InternalServerError: 500 : "{"timestamp":"2025-11-13T06:30:55.842+00:00","status":500,"error":"Internal Server Error","path":"/api/hello"}"

How to Build Resilient APIs With Resilience4j Circuit Breaker in Spring Boot

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Building a Product Catalog API with Pagination, Filtering & Sorting using Spring Boot

Circuit Breaker in Lagom Microservices

Circuit Breakers in Microservices

Introduction to Circuit Breaker Pattern: How to Build Better Software

The Markets Are Out of Order. How To #BreakTheCycle

Load Balancing Strategies for Applications: From Infrastructure to Code

Building a Product Catalog API with Pagination, Filtering & Sorting using Spring Boot

Circuit Breaker in Lagom Microservices

Circuit Breakers in Microservices

Introduction to Circuit Breaker Pattern: How to Build Better Software

The Markets Are Out of Order. How To #BreakTheCycle

Load Balancing Strategies for Applications: From Infrastructure to Code

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps