A software circuit breaker is a resilience control that temporarily rejects calls through a protected path after configured failure conditions are met. It reduces repeated unsuccessful requests and pressure on resources such as connections and worker threads, giving an unhealthy dependency an opportunity to recover. It does not itself repair that dependency.
How the State Cycle Works
A software circuit breaker typically cycles through three states: closed, open, and half-open. In the closed state, it permits calls and monitors their outcomes. When observed failures meet the configured opening conditions, it switches to open.
In the open state, new calls through the protected path are rejected without contacting the dependency. This stops that path from continuously sending requests that are likely to fail. Rejection is local to the protected path rather than a command to shut down the remote service.
After a configured waiting period or another recovery condition, the breaker may enter half-open. It then permits limited probe calls to test whether the dependency can handle requests again. Successful probes can close the circuit and restore normal traffic; failed probes can reopen it. Exact transition rules vary by implementation and configuration.
Failure Signals and Thresholds
A software circuit breaker counts the outcomes its policy treats as failures. These may include selected error responses, connection failures, or timeouts, rather than every unsuccessful application result. A rejected request caused by invalid input, for example, need not indicate that the dependency is unhealthy.
Opening conditions can use consecutive failures or a failure rate measured over an observation window. Some implementations also require enough observations before evaluating a rate. Thresholds, observation periods, and recovery conditions are configurable, not universal constants. Explicit errors can be observed without a timeout; a timeout limits waiting when a response does not arrive.
Looking for liquidity, exploring on-ramp/off-ramp services, or seeking expert guidance?
Get startedWhere the Pattern Applies
In an application, a software circuit breaker can protect calls to a remote API or another networked dependency. Its scope is the call path or group of calls it governs, not automatically the entire application. Calls through other paths may continue unless separately controlled.
This meaning is distinct from an exchange-imposed trading pause, which suspends trading under market rules, and from an electrical device that interrupts current.
Application Responsibilities and Limits
Opening a software circuit breaker does not guarantee recovery or automatically provide a fallback. A breaker may return an implementation-defined rejection result or raise an exception. The application must decide how to handle that signal, including any fallback or user-facing response, such as returning an error or using an appropriate alternative source. Any fallback has its own correctness and availability requirements.
Retries and timeouts remain separate controls: retries attempt an operation again, while timeouts bound how long the caller waits. Combining them with a breaker requires deliberate policy about which attempts are allowed and which outcomes count toward opening the circuit. Retrying a rejected call immediately does not make an open path available.
Opening the circuit also does not cancel work already accepted by the dependency or establish whether an earlier transaction completed. A caller that stopped waiting may still have triggered an operation that subsequently succeeds. Where completion is uncertain, status checks or reconciliation must resolve that uncertainty separately; the breaker’s state is not evidence of the transaction’s outcome.
Configuration Trade-offs
A very sensitive threshold may interrupt useful work after a brief recoverable failure. A permissive threshold may allow repeated delays to consume resources before the path opens. Testing should therefore cover ordinary errors, sustained failures and recovery, including the effect on requests already in flight. There is no single threshold suitable for every dependency.
For example, a payment application may stop new calls to a provider that repeatedly times out, while separately checking the status of earlier submissions. A pricing service may reject fresh fetches from an unhealthy dependency; using cached prices would require a separate policy for age and suitability. Neither example makes an alternate route safe merely because the original path is open.