---
title: Circuit Breaker
description: Protect services from cascading failures
---

# Circuit Breaker

Circuit breakers prevent cascading failures by stopping requests to failing upstreams.

## How It Works

```
Closed → Failures → Open → Timeout → Half-Open → Success → Closed
                     ↑                              ↓
                     └──────── Failures ───────────┘
```

### States

1. **Closed**: Normal operation, requests pass through
2. **Open**: Failures exceeded threshold, requests fail fast
3. **Half-Open**: Testing if service recovered

## Configuration

Circuit breakers are configured per **upstream**, not per route. The breaker
trips on a sustained error *rate* (not a raw failure count):

```yaml
upstreams:
  - name: order-service
    circuit_breaker:
      error_threshold: 50.0   # Open when ≥50% of requests error
      min_requests: 20        # Minimum requests in the window before tripping
      timeout: 30s            # Stay open this long before probing again
    instances:
      - id: order-1
        host: 10.0.0.21
        port: 8080
```

| Key | Type | Description |
| --- | --- | --- |
| `error_threshold` | float | Error-rate percentage that opens the breaker. |
| `min_requests` | integer | Minimum requests in the window before it can trip. |
| `timeout` | duration | How long the breaker stays open before probing. |

<Callout type="warn" title="Wired on the operator path">
  The `circuit_breaker` block is parsed and validated everywhere, but it is only
  wired into a live breaker on the Kubernetes/operator-driven path. For upstreams
  registered from a **static config file**, it is not yet enforced. See
  [Upstreams](/docs/octopus/configuration/upstreams).
</Callout>

## Monitoring

```bash
# View circuit breaker states
curl http://gateway:9090/_/circuit-breakers

# Prometheus metrics
octopus_circuit_breaker_state{upstream="order-service"}
octopus_circuit_breaker_failures_total{upstream="order-service"}
```

## Example

```yaml
upstreams:
  - name: payment-service
    circuit_breaker:
      error_threshold: 50.0
      min_requests: 20
      timeout: 30s
    instances:
      - id: payment-1
        host: 10.0.0.31
        port: 8080

routes:
  - path: /api/payments/*
    upstream: payment-service
```

Once payment-service exceeds a 50% error rate over at least 20 requests:
- Circuit opens
- Requests fail fast without hitting the upstream
- After 30s, the circuit probes again (half-open)
- If probes succeed, the circuit closes

## See Also

- [Health Checks](/docs/octopus/concepts/health-checks)
- [Load Balancing](/docs/octopus/concepts/load-balancing)
- [Upstreams configuration](/docs/octopus/configuration/upstreams)