> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vikat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Circuit breaker

> Stop hammering a provider that is failing, and fall back while it recovers.

<Warning>
  This page previously described Azure PTU-to-pay-as-you-go spillover driven by
  response-header signals. The plugin does not do that, and configuring it as
  described would convert a soft capacity event into a hard outage: the breaker
  returns 503 on an open circuit rather than spilling to another deployment.
  It has been rewritten to match the code.
</Warning>

## What it does

Counts consecutive failures per **provider + model**. After
`failure_threshold` in a row, that pair's breaker opens and requests short-circuit
instead of queueing behind a provider that is not answering. After
`cooldown_seconds`, one trial request is admitted; if it succeeds the breaker
closes, if it fails the cooldown restarts.

Breakers are per provider+model, so OpenAI failing does not stop Anthropic, and
one bad model does not take out a healthy one on the same provider.

## Configuration

```json theme={null}
{
  "name": "circuitbreaker",
  "enabled": true,
  "config": {
    "failure_threshold": 5,
    "cooldown_seconds": 30,
    "allow_fallbacks": true
  }
}
```

| Field               | Default | Meaning                                             |
| ------------------- | ------- | --------------------------------------------------- |
| `failure_threshold` | 5       | Consecutive upstream failures that open a breaker.  |
| `cooldown_seconds`  | 30      | How long it stays open before a trial request.      |
| `allow_fallbacks`   | `true`  | Whether fallback providers may be tried while open. |

## Leave `allow_fallbacks` on

With it on, an open breaker is nearly invisible to callers: the request routes to
a fallback and succeeds. Turning it off makes an open breaker return 503, which
is occasionally what you want — a hard stop while you investigate — and is
otherwise how a single provider's incident becomes yours.

## What it is not

* **Not spillover.** There is no capacity-based routing between deployments, and
  no reading of provider rate-limit headers to decide where to send traffic.
* **Not shared between nodes.** Each replica keeps its own failure counts, so a
  provider outage is detected independently by each. That is usually fine — every
  node sees the same failures — but a low-traffic node takes longer to notice.