This article explains how to design and implement your own circuit breaker in Spring Boot using explicit failure tracking, a scheduler-driven recovery model, and clear state transitions.
Instead of relying solely on Resilience4j, we’ll walk through the internal mechanics so you understand how circuit breakers actually work.
What We’ll Cover
Prerequisites and Technical Context
This article assumes you are comfortable with core Spring Boot and Java concepts. We won’t cover framework fundamentals or basic concurrency principles in depth. Here’s what you’ll need to know:
Spring Boot Basics
You should be comfortable with how dependency injection works in Spring, how to define @Configuration classes and @Bean definitions, and the basic service-layer structure of a Spring application. In this tutorial, we’ll treat the circuit breaker as a plain Java component and wire it into Spring through configuration classes rather than annotations.
Java Concurrency Fundamentals
You don’t need to be a concurrency expert, but you should be comfortable with Java’s basic concurrency tools. The implementation uses AtomicInteger, volatile fields, a ScheduledExecutorService, and simple synchronization, so you should understand why shared mutable state is dangerous, how atomic operations differ from synchronized blocks, and why state transitions in a shared state machine must be serialized.
Functional Interfaces
The circuit breaker exposes an execute(Supplier<T>) method, so you should be comfortable using Supplier<T>, writing simple lambda expressions, and wrapping outbound service calls inside a function you can pass to the breaker.
Resilience4j Basics
You don’t need hands-on Resilience4j experience, but you should know that it’s a lightweight Java fault-tolerance library that offers circuit breakers, retries, rate limiters, bulkheads, and is commonly used in Spring Boot via annotations or config. In this article we’ll only reference Resilience4j for comparison, not for actual configuration or usage.
What Is a Circuit Breaker in Distributed Systems?
A circuit breaker is a fault-tolerance pattern that stops a system from repeatedly attempting operations that are likely to fail.
The name comes from electrical engineering. In a physical circuit, a breaker “opens” when the current becomes unsafe, preventing damage. After a cooldown period, it allows current to flow again to test whether the issue has been resolved.
In software, the same principle applies. When Service A depends on Service B, and Service B becomes slow or unavailable, naïvely retrying every request can:
Exhaust thread pools
Saturate connection pools
Increase latency across the system
Trigger cascading failures
Bring down otherwise healthy services
Instead of continuing to send requests to a failing dependency, a circuit breaker:
Detects repeated failures
Opens the circuit and blocks calls
Fails fast without attempting the operation
Periodically tests whether the dependency has recovered
This turns uncontrolled failure into controlled degradation.
Why Circuit Breakers Matter in Spring Boot
Because circuit breakers are a foundational resilience pattern in distributed systems, most Spring Boot teams reach immediately for Resilience4j or legacy Hystrix‑style abstractions – and for good reason. These libraries are mature, well-tested, and production-proven.
However, treating circuit breakers as black boxes often leads to:
Misconfigured thresholds
Incorrect assumptions about failure handling
Difficulty extending behavior beyond library defaults
Debugging issues where “the breaker opened, but we don’t know why”
Building your own circuit breaker – even if you never ship it to production – forces you to understand the mechanics that actually protect your system. In some cases, a custom implementation also provides flexibility that general-purpose libraries cannot.
Why Circuit Breakers Are Foundational
Circuit breakers are a foundational resilience pattern because they protect your scarcest resources (like threads, network and database connections, and CPU time) from being exhausted by a failing dependency.
Without a breaker, a single slow service can gradually consume all of those resources and turn a local problem into a system-wide outage.
Circuit breakers enforce isolation boundaries between services and sit alongside timeouts, retries, bulkheads, and rate limiters, but they make one crucial strategic choice that simple retries do not: they stop trying for now. That decision is what prevents cascading collapse.
What Problem Circuit Breakers Solve That Timeouts and Retries Do Not
Timeouts and retries are reactive: timeouts cap how long you wait, and retries try the same operation again in the hope it succeeds.
A circuit breaker is proactive. It monitors failure patterns and, once a threshold is crossed, temporarily disables the failing integration point so new requests are rejected immediately instead of timing out.This dramatically reduces resource waste and stabilizes the system under stress.
The Circuit Breaker State Model
Any circuit breaker – library-based or custom – follows the same conceptual state machine.
Closed: In the Closed state, all requests are allowed and failures are simply monitored.
Open: When failures cross a configured threshold, the breaker moves to Open, blocks new requests, and makes them fail immediately.
Half-Open: After a cooldown period, it enters Half-Open, where it lets a small number of trial requests through to test whether the dependency has recovered; based on those results, it either returns to Closed or goes back to Open.
The complexity lies not in the states themselves, but in how and when transitions occur.
Why Not Just Use Resilience4j?
Resilience4j is excellent, but there are valid reasons to build your own:
You want non-standard failure logic (for example, domain-aware errors).
You need custom recovery strategies.
You want state persisted or shared differently.
You need tight integration with business metrics.
You want to understand the internals for tuning and debugging.
More importantly, understanding the internals prevents misuse. Many production incidents stem from misconfigured circuit breakers rather than missing ones.
Design Goals for a Custom Circuit Breaker
Before writing any code, we need to be clear about what “correct” behavior looks like. A circuit breaker seems simple in theory, but subtle design mistakes can introduce race conditions, false openings, or silent failures where it stops protecting the system.
The following goals shape a predictable and production-safe implementation.
Thread-Safe and Low Overhead
The breaker sits on the hot path of outbound calls, so every protected request passes through it. If it introduces lock contention or heavy synchronization, it quickly becomes a bottleneck.
The implementation needs to avoid coarse-grained locking, use atomic primitives carefully, and serialize state transitions without blocking execution more than necessary. Thread safety is non‑negotiable: a circuit breaker that misbehaves under concurrency is worse than having no breaker at all.
Predictable State Transitions
Circuit breakers are state machines. If their transitions are inconsistent or prone to races, you end up with split‑brain behavior – one thread believes the breaker is OPEN while another believes it is CLOSED – and your protection becomes undefined.
To avoid this, every transition (CLOSED → OPEN → HALF_OPEN → CLOSED) must be explicit, atomic, and deterministic, all guarded by a single transition mechanism. In this design, predictability matters far more than cleverness.
Explicit Failure Tracking
Not every failure should open the breaker. If you blindly count every exception, you risk opening the breaker on client validation errors, treating business rule violations as infrastructure failures, and hiding real domain bugs behind resilience logic.
Failure classification has to be deliberate: the breaker should react only to infrastructure‑level problems such as timeouts, connection errors, and 5xx responses, not to domain logic errors. Keeping that separation ensures your resilience layer stays aligned with actual failure modes.
Time-Based Recovery Using a Scheduler
Some implementations check timestamps on every request to decide when to move from OPEN to HALF_OPEN, adding extra branching to the hot path.
Instead, this design uses a scheduler: when the breaker opens, it schedules a recovery attempt, keeps the OPEN state purely fail‑fast, and avoids request‑driven polling. That approach reduces branching and contention under load. Recovery should be controlled and predictable – not opportunistic.
Framework-Agnostic Core Logic
The breaker itself should be plain Java – no Spring annotations, no AOP, and no direct framework coupling. That choice makes unit testing easier, keeps the component portable, and preserves a clean separation of concerns with less hidden magic. Spring should wrap the breaker, not define it, so your resilience strategy is not trapped inside any one framework’s abstractions.
Easy Integration into Spring Boot
Although the core logic is framework‑agnostic, it still needs to plug cleanly into a Spring application. That means wiring it via @Configuration, supporting dependency injection, and calling it from clear execution points in your service layer. Resilience behavior should be obvious in code reviews. Hiding it behind annotations often leads to confusion when you are debugging production issues.
How to Build a Minimal Working CircuitBreaker Class
Now let’s turn the conceptual components into a single cohesive class. This is still a minimal implementation, but it’s complete enough to demonstrate state, failure tracking, scheduling, and execution logic in one place.
A minimal circuit breaker consists of:
State holder
Failure tracker
Transition rules
Scheduler for recovery
Execution guard
public final class CircuitBreaker {
enum State {
CLOSED,
OPEN,
HALF_OPEN
}
private final ScheduledExecutorService scheduler;
private final int failureThreshold;
private final int halfOpenTrialLimit;
private final Duration openCooldown;
private final AtomicInteger failureCount = new AtomicInteger(0);
private final AtomicInteger halfOpenTrials = new AtomicInteger(0);
// All transitions go through this field, guarded by `synchronized` blocks.
private volatile State state = State.CLOSED;
public CircuitBreaker(
ScheduledExecutorService scheduler,
int failureThreshold,
int halfOpenTrialLimit,
Duration openCooldown
) {
this.scheduler = scheduler;
this.failureThreshold = failureThreshold;
this.halfOpenTrialLimit = halfOpenTrialLimit;
this.openCooldown = openCooldown;
}
public <T> T execute(Supplier<T> action) {
// 1. Guards the functionality based on its current state.
//We are using synchronized block for thread safety.
// Make sure another thread does not override our current state
State current;
synchronized (this) {
current = state;
if (current == State.OPEN) {
throw new IllegalStateException("Circuit breaker is OPEN. Call rejected.");
}
if (current == State.HALF_OPEN) {
int trials = halfOpenTrials.incrementAndGet();
if (trials > halfOpenTrialLimit) {
// Too many trial requests; fail fast.
halfOpenTrials.decrementAndGet();
throw new IllegalStateException("Circuit breaker is HALF_OPEN. Trial limit exceeded.");
}
}
}
// 2. Execute the business functionality here. For e.g API calls to other systems
try {
T result = action.get();
// 3. Record success
onSuccess();
return result;
} catch (Throwable t) {
// 3. Record failure
onFailure(t);
// 4. Propagate to caller
if (t instanceof RuntimeException re) {
throw re;
}
if (t instanceof Error e) {
throw e;
}
throw new RuntimeException(t);
}
}
private void onSuccess() {
synchronized (this) {
failureCount.set(0);
if (state == State.HALF_OPEN) {
// A successful trial closes the breaker.
transitionToClosed();
}
}
}
private void onFailure(Throwable t) {
// Example: only count "server-side" failures.
boolean breakerRelevant = true; // placeholder for domain-specific checks
if (!breakerRelevant) {
return;
}
synchronized (this) {
int failures = failureCount.incrementAndGet();
if (state == State.CLOSED && failures >= failureThreshold) {
transitionToOpen();
} else if (state == State.HALF_OPEN) {
// Any failure in HALF_OPEN sends us back to OPEN.
transitionToOpen();
}
}
}
private void transitionToOpen() {
state = State.OPEN;
// Reset counters so the next CLOSED phase starts clean.
failureCount.set(0);
halfOpenTrials.set(0);
scheduleHalfOpen();
}
private void transitionToHalfOpen() {
synchronized (this) {
state = State.HALF_OPEN;
halfOpenTrials.set(0);
}
}
private void transitionToClosed() {
state = State.CLOSED;
failureCount.set(0);
halfOpenTrials.set(0);
}
private void scheduleHalfOpen() {
scheduler.schedule(
this::transitionToHalfOpen,
openCooldown.toMillis(),
TimeUnit.MILLISECONDS
);
}
}
Now we’ll walk through each responsibility in that class: why the fields exist, how state transitions work, where concurrency guarantees matter, how execution is guarded, and how the scheduler drives recovery.
Each subsection maps directly back to part of this class – we’re not introducing new concepts, just explaining the behavior implemented within the code above.
Concurrency and State Transition Guarantees
Although the breaker uses atomic primitives for counters and a volatile state field, this only works because all state transitions are guarded consistently.
In practice, every transition – CLOSED → OPEN, OPEN → HALF_OPEN, HALF_OPEN → CLOSED – must be performed under the same synchronization mechanism as shown below: either a single lock or a CAS-based state machine. Mixing unsynchronized state writes with atomic counters can lead to split-brain behavior (for example, one thread reopening the breaker while another closes it).
synchronized (this) {
current = state;
if (current == State.OPEN) {
throw new IllegalStateException("Circuit breaker is OPEN. Call rejected.");
}
if (current == State.HALF_OPEN) {
int trials = halfOpenTrials.incrementAndGet();
if (trials > halfOpenTrialLimit) {
// Too many trial requests; fail fast.
halfOpenTrials.decrementAndGet();
throw new IllegalStateException("Circuit breaker is HALF_OPEN. Trial limit exceeded.");
}
}
}
The rule is simple: reads may be optimistic, but writes and transitions must be serialized.
Explaining the State Model in the Class
At the core of the implementation is a simple but strict state machine represented by the State enum: CLOSED, OPEN and HALF_OPEN
The state field is declared volatile so changes are immediately visible across threads. When one thread moves the breaker to a new state, other threads see that update without delay.
Alongside the state, the class maintains failureCount and halfOpenTrials counters using AtomicInteger (Refer to the code in the above section). These track how failures accumulate and how many recovery attempts we have made, without resorting to coarse‑grained locks.
The key design idea is separation of responsibilities: the enum captures the current mode of operation, while the atomic counters hold the metrics that influence state transitions. Atomic increments alone do not guarantee safe transitions, though, so all updates to the state still follow a consistent serialization strategy to avoid race conditions.
enum State {
CLOSED,
OPEN,
HALF_OPEN
}
This structure gives us a clear foundation: a small, explicit state machine with observable transition boundaries.
Failure Tracking Inside the Class
private void onFailure(Throwable t) {
// Example: only count "server-side" failures.
boolean breakerRelevant = true; // placeholder for domain-specific checks
if (!breakerRelevant) {
return;
}
synchronized (this) {
int failures = failureCount.incrementAndGet();
if (state == State.CLOSED && failures >= failureThreshold) {
transitionToOpen();
} else if (state == State.HALF_OPEN) {
// Any failure in HALF_OPEN sends us back to OPEN.
transitionToOpen();
}
}
}
In this implementation, failure tracking is intentionally simple: we count consecutive failures. Each time a protected call throws an exception we classify as breaker‑relevant, failureCount is incremented. On a successful call, the counter resets.
I chose consecutive failures for clarity rather than sophistication. More advanced strategies, like sliding time windows or failure ratios, introduce extra state and timing complexity. When you’re learning how a breaker works, a simple counter makes the transition rules easy to reason about and easy to test.
Equally important, the breaker should not treat every exception the same. Domain validation errors, client misuse, and business rule violations shouldn’t affect the breaker’s state. Only infrastructure‑level problems (like timeouts, connection failures, or 5xx responses) should move the breaker toward OPEN. That separation keeps the breaker focused on dependency instability, not application bugs or bad inputs.
How Closed State Transitions to Open
When the breaker is in the CLOSED state, all requests flow through normally. In this phase the breaker is purely observational: it monitors outcomes and increments failureCount whenever a breaker‑relevant exception occurs.
Inside the onFailure method (shown in the above section), once the failureCount exceeds the configured threshold, the breaker transitions to OPEN. This transition must be atomic and serialized – otherwise, multiple threads could try to open the breaker at the same time, leading to inconsistent scheduling or duplicate recovery tasks.
private void transitionToOpen() {
state = State.OPEN;
// Reset counters so the next CLOSED phase starts clean.
failureCount.set(0);
halfOpenTrials.set(0);
scheduleHalfOpen();
}
Moving to OPEN immediately changes system behavior. From that point on, new requests are rejected without attempting the protected operation, which shields downstream services and preserves local resources such as threads and connection pools.
OPEN State Behavior in the Class
The OPEN state represents pure fail‑fast behavior. While the breaker is open, no protected calls are executed. The execute() method immediately throws an exception indicating that the circuit is open.
public <T> T execute(Supplier<T> action) {
// 1. Guards the functionality based on its current state.
//We are using synchronized block for thread safety.
// Make sure another thread does not override our current state
State current;
synchronized (this) {
current = state;
if (current == State.OPEN) {
throw new IllegalStateException("Circuit breaker is OPEN. Call rejected.");
}
....
}
This behavior is not about improving latency – it is about resource protection. Letting calls continue and simply “wait for timeouts” would still tie up threads and connections. The value of the OPEN state is that it refuses to participate in propagating failure at all.
In this state, the breaker has a single responsibility: wait for the scheduled recovery attempt. It doesn’t check timestamps on each request or poll in the hot path. Its behavior is deterministic: reject immediately and let the scheduler decide when to try again.
Scheduler‑Driven Recovery: Entering HALF_OPEN
When the breaker transitions to OPEN, it immediately schedules a delayed task using the injected ScheduledExecutorService. After the configured cooldown period elapses, that task transitions the breaker to HALF_OPEN.
// Refer below methods from the main code
private void transitionToOpen() {
state = State.OPEN;
// Reset counters so the next CLOSED phase starts clean.
failureCount.set(0);
halfOpenTrials.set(0);
scheduleHalfOpen(); // schedule a delayed task after changing the state to State.Open
}
private void scheduleHalfOpen() {
scheduler.schedule(
this::transitionToHalfOpen,
openCooldown.toMillis(),
TimeUnit.MILLISECONDS
);
}
This design keeps time-based logic out of the request execution path. Rather than checking elapsed time on every call, the breaker delegates recovery timing to a dedicated scheduler thread. This reduces conditional logic under load and keeps the execute() method focused on guarding execution.
The scheduler must be reliable and isolated. A single-threaded executor is typically sufficient because transitions are rare and lightweight. More importantly, transitions should be idempotent so that unexpected rescheduling does not corrupt state.
Spring Boot Scheduler Example
In Spring Boot, you can wire a dedicated ScheduledExecutorService bean to drive state transitions instead of using plain Java threads.
@Configuration
class CircuitBreakerConfig {
// First bean
@Bean
ScheduledExecutorService circuitBreakerScheduler() {
return Executors.newSingleThreadScheduledExecutor();
}
// Second bean
@Bean
CircuitBreaker circuitBreaker(ScheduledExecutorService circuitBreakerScheduler) {
return new CircuitBreaker(
circuitBreakerScheduler,
5, // failureThreshold
2, // halfOpenTrialLimit
Duration.ofSeconds(30) // openCooldown
);
}
}
The configuration class above wires the circuit breaker into the Spring container without introducing framework coupling into the breaker itself.
The first bean circuitBreakerScheduler() defines a dedicated ScheduledExecutorService. This executor is responsible exclusively for time-based state transitions. When the breaker moves to OPEN, it uses this scheduler to queue a delayed task that transitions the state to HALF_OPEN.
Using a single-threaded executor is intentional. Circuit breaker transitions are lightweight and infrequent, so parallel scheduling is unnecessary. A single thread guarantees serialized transition execution and avoids overlapping recovery attempts.
The second bean constructs the CircuitBreaker itself. Here we inject the scheduler and configure three things: a failure threshold of 5 consecutive errors, a half‑open trial limit of 2 test requests, and a 30‑second cooldown before we attempt recovery again. This configuration makes the breaker’s behavior explicit and easy to reason about – there are no hidden properties files or annotations, because everything that affects resilience is defined in one place.
At this point, the breaker is a fully managed Spring bean that you can inject into services and use programmatically.
How This Connects to Execution Flow
Once registered as a bean, the breaker becomes part of the application’s dependency graph. A typical service might inject it and wrap outbound calls:
@Service
class ExternalApiService {
private final CircuitBreaker circuitBreaker;
private final RestTemplate restTemplate;
ExternalApiService(CircuitBreaker circuitBreaker, RestTemplate restTemplate) {
this.circuitBreaker = circuitBreaker;
this.restTemplate = restTemplate;
}
public String callExternal() {
return circuitBreaker.execute(() ->
restTemplate.getForObject("http://external/api", String.class)
);
}
}
Every outbound call to the external system flows through the breaker’s execute() method, which enforces the current state rules before allowing the call to proceed. That makes resilience behavior explicit at the integration boundary: anyone reviewing the service can immediately see that the call is protected. There is no hidden interception layer and no AOP proxy quietly changing behavior at runtime.
Scheduler Design and Thread Safety
The scheduler’s only responsibility is delayed state transition. It doesn’t execute business logic and it doesn’t evaluate request outcomes. Its purpose is narrowly scoped: move the breaker from OPEN to HALF_OPEN after a cooldown.
Because the executor is single-threaded, scheduled tasks cannot overlap. But this doesn’t eliminate concurrency concerns entirely. Request threads may still attempt transitions at the same time the scheduler fires. For this reason, transition methods such as transitionToHalfOpen() and transitionToOpen() must remain serialized and idempotent.
In other words, even though the scheduler simplifies time-based recovery, it doesn’t replace the need for careful state management.
The architectural separation looks like this:
Request threads → enforce execution rules and record outcomes
Scheduler thread → handle time-based recovery transitions
Keeping these responsibilities separate reduces complexity in the hot path and improves predictability under load.
Why We Avoid @Scheduled for This Design
Spring provides @Scheduled as an alternative mechanism for time-based tasks. While convenient, it introduces global scheduling behavior and reduces isolation.
By using a dedicated ScheduledExecutorService for the breaker, we avoid interference with other scheduled jobs, keep lifecycle control explicit, and tie scheduling logic directly to breaker transitions.
This design reinforces the principle that resilience components should be isolated and predictable.
Bringing It All Together
At this stage, the full interaction looks like this:
A service wraps its dependency call with
circuitBreaker.execute().If the breaker is CLOSED, the call proceeds and any relevant failures are counted.
When failures exceed the threshold, the breaker moves to OPEN and schedules a recovery attempt.
While OPEN, calls fail immediately without hitting the downstream system.
After the cooldown period, the scheduler transitions the breaker to HALF_OPEN.
A small number of trial calls then decide whether the breaker returns to CLOSED or goes back to OPEN.
Nothing is hidden: every transition is visible in code, every configuration value is explicit, and each thread involved has a single responsibility. That clarity is what makes a custom implementation useful for learning – and safe when it is designed correctly.
Observability: Making the Breaker Understandable
A circuit breaker without observability is risky. At a minimum you should expose the current state, the failure count, the time of the last transition, and how long the breaker has been open.
On the metrics side, track how often the breaker opens, how many calls are rejected per second, and the success rate of recovery attempts.
Your logs should record state transitions at INFO level and failure classification decisions at DEBUG. With that level of visibility, your custom breaker is often easier to understand and tune than what many libraries provide out of the box..
Handling Different Failure Types
Not all failures are equal.
API Response Timeouts → breaker‑relevant
API 5xx responses → breaker‑relevant
API 4xx responses → usually not
Any data or business validation errors → never
A custom breaker lets you apply this kind of business‑aware classification, which is often hard to express cleanly with generic libraries.
Custom Breaker vs Resilience4j
| Aspect | Custom Breaker | Resilience4j |
| Learning value | High | Low |
| Flexibility | High | Medium |
| Time to implement | Medium | Low |
| Operational maturity | Depends | High |
| Custom failure logic | Easy | Limited |
| Tooling / metrics | You wire metrics, logs, observability manually | Built-in metrics, logging, and integrations |
The choice is not binary. Many teams prototype with a custom breaker and later replace it with Resilience4j – now correctly configured.
When You Should Not Build Your Own
Do not build a custom breaker if:
You lack observability.
You do not understand concurrency.
You need advanced features immediately.
Your system is safety-critical.
For example, if you are building a payments platform with strict SLAs and cannot afford to battle-test a custom breaker, stick with a mature library like Resilience4j. The risk of subtle concurrency bugs, misclassified failures, or scheduler misconfigurations is too high to experiment in production.
Extending the Design
Once you understand the core, you can add:
Sliding window metrics.
Adaptive thresholds.
Persistent breaker state.
Distributed breakers (per dependency).
Integration with feature flags.
These extensions are much easier when you control the internals.
Common Mistakes
Common mistakes when working with circuit breakers include:
Opening the breaker on the first failure.
Blocking threads while OPEN.
Allowing unlimited HALF_OPEN requests.
Treating all exceptions equally.
Ignoring observability.
Most of these happen when using libraries without understanding them.
Conclusion
Resilience libraries are powerful, but they are not magic. A circuit breaker is fundamentally a state machine with failure tracking and time-based transitions. Building your own – even once – forces you to internalize this reality.
In Spring Boot systems, a custom circuit breaker:
Clarifies failure semantics.
Improves debugging.
Enables domain-specific resilience.
Makes you a better user of Resilience4j.
You may never deploy your own breaker to production. But after building one, you will never configure a circuit breaker blindly again.