42 — Circuit Breakers (Resilience4j)

Concept overview

A circuit breaker observes dependency outcomes and temporarily rejects calls when configured failure or slow-call conditions indicate poor health. Closed permits calls, open rejects them, and half-open allows a limited recovery sample. It is distinct from a timeout, retry policy, rate limiter, or concurrency bulkhead; those controls address different failure dimensions.

Resilience4j provides configurable count-based or time-based sliding windows, minimum call counts, failure and slow-call thresholds, and half-open behavior. Choose failure classification carefully. A user's invalid request should not normally declare the entire dependency unhealthy, and a breaker does not cancel calls already in flight.

Why it matters in production

Proof of concept

A prototype can simulate dependency errors and observe state transitions. Avoid selecting production thresholds from a handful of successful demo calls.

Production

Production tunes windows and minimum samples to actual traffic, scopes breakers by dependency or meaningful failure domain, and defines a useful open-state response.

Enterprise scale

At scale, too many fine-grained breakers create state and metric cardinality, while one global breaker can spread a localized outage. Test recovery under load and ensure probes do not all arrive simultaneously across instances.

Architecture components

Outcome classifier

Distinguishes dependency failures and slow calls from expected business rejections.

Sliding-window recorder

Tracks the sample used to evaluate configured failure and latency conditions.

Breaker state

Controls closed, open, and limited half-open admission.

Fallback handler

Returns cached, partial, queued, or unavailable results according to business policy.

State telemetry

Exposes transitions, rejected calls, sample counts, and recovery behavior.

The architecture, mapped

stateDiagram-v2
 [*] --> Closed
 Closed --> Open: Minimum sample and failure threshold met
 Open --> HalfOpen: Recovery wait completed
 HalfOpen --> Closed: Probe outcomes acceptable
 HalfOpen --> Open: Probe outcomes unhealthy
 Closed --> Closed: Record admitted call outcomes
 Open --> Open: Reject ordinary calls

Runtime flow

1. 1

   Classify call

   Select the breaker for the dependency and operation's actual failure domain.

2. 2

   Check admission

   Permit normal traffic when closed, reject when open, or allocate a half-open probe.

3. 3

   Execute bounded request

   Apply a separate timeout and concurrency control to the admitted call.

4. 4

   Record outcome

   Count configured failures and slow calls while excluding expected business responses.

5. 5

   Transition state

   Open only after the required sample and thresholds are met, then wait according to recovery policy.

6. 6

   Probe and restore

   Admit limited tests, close after acceptable results, or reopen when the dependency remains unhealthy.

Protecting an itinerary assistant from a failing inventory API

Travel operations · Illustrative enterprise scenario, not a reported customer outcome.

Business situation

A travel platform's assistant checks hotel inventory while assembling business-trip options.

The problem

A slow supplier endpoint causes repeated waits and consumes worker capacity across unrelated itinerary requests.

Agent requirement

The assistant must stop overloading the supplier and continue with clearly identified available evidence.

Architecture

A supplier-scoped breaker records relevant errors and slow calls, while timeouts and bulkheads protect individual requests and worker capacity.

Runtime

• When the configured health conditions are met, the breaker opens and the assistant excludes unverified supplier inventory.
• After the recovery interval, limited probes test the supplier before normal traffic resumes.

Failure scenario

If probes fail, the breaker reopens and the itinerary remains explicit about missing inventory rather than showing stale availability as current.

Operational impact

Track state duration, rejected calls, probe outcomes, and unaffected supplier latency. A breaker improves containment, not the failed dependency itself.

Architecture tradeoffs

Failure scenarios & recovery

Common architecture mistakes

Using a breaker as a concurrency limit

Add a bulkhead or semaphore for in-flight capacity.

Retrying immediately when the breaker is open

Respect the open-state policy and avoid retry amplification.

Sharing one breaker across unrelated suppliers

Scope health to the actual dependency boundary.

When to choose this pattern

Choose it when

• A remote dependency can fail repeatedly or become slow.
• Fast rejection enables a meaningful degraded response.
• Sufficient traffic exists to estimate health sensibly.

Avoid it when

• Failures are independent caller validation errors.
• Every rejected call would trigger more uncontrolled retries.
• No operational owner can tune and observe recovery.

Architecture checklist

• Define failure and slow-call classification.
• Set minimum sample and window type.
• Scope breakers by failure domain.
• Pair with timeouts and concurrency limits.
• Limit and observe half-open probes.
• Test fallback and recovery under load.

Related concepts

• 45 — Graceful Degradation
• 49 — Timeout Policies
• 50 — Exponential Backoff with Jitter
• 56 — Load Balancing LLM Requests
• 59 — Cascade Failure Prevention

Primary references

• Resilience4j: CircuitBreaker