# Understanding the States of OmniRoute's Circuit Breaker: CLOSED, OPEN, HALF-OPEN, and DEGRADED

> Explore OmniRoute circuit breaker states: CLOSED, OPEN, HALF-OPEN, and DEGRADED. Learn how these states manage request flow and prevent cascading failures.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-21

---

**OmniRoute’s circuit breaker implements four distinct states—CLOSED, DEGRADED, OPEN, and HALF_OPEN—to govern request flow and protect upstream providers from cascading failures.**

The OmniRoute repository provides a resilient request routing layer that leverages the circuit breaker pattern to prevent cascade failures across AI providers. Understanding the **states of OmniRoute's circuit breaker** is essential for configuring robust error handling and maintaining high availability in production environments. The implementation defines these lifecycle states in [`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts), with transition logic controlled by configurable failure thresholds and timeout parameters.

## The Four OmniRoute Circuit Breaker States

### CLOSED (Normal Operation)

In the **CLOSED** state, the circuit breaker permits all requests to flow to the provider. This is the default starting state and indicates healthy upstream service. According to the source code in [`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts), the breaker returns to CLOSED after successful probe requests or when failure counts decay below the degradation threshold.

### DEGRADED (Warning Threshold)

The **DEGRADED** state acts as an early warning system. When the failure count exceeds the `degradationThreshold` (approximately 60% of the `failureThreshold`) but remains below the full failure limit, the system logs warnings while still allowing requests. This intermediate state prepares the system for a potential transition to OPEN without immediately blocking traffic.

### OPEN (Short-Circuit)

When failures reach the configured `failureThreshold`, the breaker transitions to **OPEN**, immediately rejecting new requests with a `CircuitBreakerOpenError`. This short-circuit behavior prevents overwhelming struggling providers and allows them time to recover. The transition logic is implemented between lines 68-73 of the core utility file.

### HALF_OPEN (Recovery Probe)

After the `resetTimeout` expires while in OPEN state, the breaker enters **HALF_OPEN** and allows a limited number of probe requests (controlled by `halfOpenRequests`) to test provider health. Successful probes return the breaker to CLOSED; failures escalate the back-off period and return it to OPEN.

## State Transition Logic and Thresholds

The state machine governs transitions through configurable thresholds defined in the circuit breaker configuration:

- **degradationThreshold**: Approximately 60% of the failure threshold, triggering the DEGRADED state before full tripping
- **failureThreshold**: The absolute count of failures required to trip the breaker to OPEN
- **resetTimeout**: The cooldown period (in milliseconds) before transitioning from OPEN to HALF_OPEN
- **halfOpenRequests**: The number of allowed probe requests during the HALF_OPEN state to verify recovery

## Implementing Circuit Breakers in OmniRoute

To utilize the circuit breaker pattern in your OmniRoute implementation, import the utilities from the shared module:

```typescript
import { getCircuitBreaker, STATE } from '@/shared/utils/circuitBreaker';

// Create a breaker for the "openai" provider
const openAiBreaker = getCircuitBreaker('openai', {
  failureThreshold: 5,          // Trip to OPEN after 5 failures
  resetTimeout: 30_000,         // 30-second back-off before HALF_OPEN
  halfOpenRequests: 1,          // Allow one probe request
});

// Inspect current state
if (openAiBreaker.getStatus().state === STATE.CLOSED) {
  console.log('Provider is healthy – proceed with requests');
}

// Wrap a request with the breaker
try {
  const result = await openAiBreaker.execute(() => fetchOpenAiChat(payload));
  console.log('Chat response:', result);
} catch (err) {
  // CircuitBreakerOpenError is thrown when the breaker is OPEN or HALF_OPEN and no probes remain
  console.warn('Request blocked by circuit breaker:', err);
}

```

For administrative control, you can force a reset:

```typescript
openAiBreaker.reset();   // Forces state back to CLOSED and clears counters

```

## Monitoring Circuit Breaker Health

OmniRoute exposes breaker status for observability through the registry:

```typescript
import { getAllCircuitBreakerStatuses } from '@/shared/utils/circuitBreaker';

console.table(getAllCircuitBreakerStatuses());

```

This function returns the current state of all registered breakers, enabling real-time monitoring of provider health across the system. The implementation also tracks specialized breakers, such as those defined in [`open-sse/services/tokenRefresh/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/tokenRefresh/circuitBreaker.ts), which follow the identical four-state model for authentication flows.

## Summary

- OmniRoute implements **four circuit breaker states**: CLOSED, DEGRADED, OPEN, and HALF_OPEN to manage provider health
- The **DEGRADED** state provides early warning at ~60% of the failure threshold before full tripping
- **OPEN** state rejects requests immediately via `CircuitBreakerOpenError` to prevent cascade failures
- **HALF_OPEN** allows configurable probe requests to test recovery before returning to CLOSED
- State machine logic resides in [`src/shared/utils/circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/circuitBreaker.ts) with transitions controlled by `failureThreshold`, `resetTimeout`, and `halfOpenRequests`

## Frequently Asked Questions

### What triggers the transition from CLOSED to OPEN in OmniRoute's circuit breaker?

The transition occurs when the failure count reaches the configured `failureThreshold` or when an immediate-open condition is met for critical failure kinds. The system passes through the intermediate DEGRADED state when failures exceed the degradation threshold (approximately 60% of the failure limit) before reaching the full OPEN state.

### How does the HALF_OPEN state determine whether to close or reopen the circuit?

While in HALF_OPEN, the breaker allows a limited number of requests defined by `halfOpenRequests`. If these probe requests succeed, the breaker transitions to CLOSED. If they fail, the breaker returns to OPEN with an escalated back-off timeout to prevent premature retry attempts.

### Can I manually override the circuit breaker state in OmniRoute?

Yes. The [`circuitBreaker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/circuitBreaker.ts) implementation provides a `reset()` method that forces the breaker back to the CLOSED state and clears all internal failure counters. This is useful for administrative recovery actions or maintenance windows.

### What is the difference between DEGRADED and OPEN states?

The DEGRADED state acts as a pre-alarm zone where requests still pass through but the system logs warnings when failure counts exceed the degradation threshold (~60% of the failure limit). The OPEN state represents a full short-circuit where new requests are immediately rejected to protect the upstream provider.