# `CCXT.CircuitBreaker`
[🔗](https://github.com/ZenHive/ccxt_client/blob/main/lib/ccxt/circuit_breaker.ex#L1)

Per-exchange circuit breakers using the `:fuse` Erlang library.

Prevents cascade failures when exchanges are down. Each exchange has isolated
state — binance down does not affect bybit.

## How It Works

1. Each exchange gets its own fuse named `:ccxt_fuse_<exchange_id>`
2. Fuses are installed lazily on first request
3. After N failures within M milliseconds, the circuit opens
4. Opened circuits reject requests immediately (fast fail)
5. After reset timeout, circuit closes and allows requests again

## What Triggers the Circuit

| Response | Melts? | Reason |
|----------|--------|--------|
| HTTP 500+ | Yes | Server error |
| Timeouts | Yes | Server unresponsive |
| Connection refused | Yes | Server unavailable |
| HTTP 429 | **No** | Handled by rate limiter |
| HTTP 4xx | **No** | Client error, not server issue |

## Configuration

    config :ccxt_client, :circuit_breaker,
      enabled: true,
      max_failures: 5,
      window_ms: 10_000,
      reset_ms: 15_000

# `all_statuses`

```elixir
@spec all_statuses() :: %{required(String.t()) =&gt; :ok | :blown}
```

Returns status of all installed circuit breakers.

# `check`

```elixir
@spec check(String.t()) :: :ok | :blown
```

Checks if requests are allowed for an exchange.

Installs the fuse lazily if not already installed.

# `config`

```elixir
@spec config() :: %{
  enabled: boolean(),
  max_failures: pos_integer(),
  window_ms: pos_integer(),
  reset_ms: pos_integer()
}
```

Returns circuit breaker configuration.

# `record_failure`

```elixir
@spec record_failure(String.t()) :: :ok
```

Records a failed request. Enough melts within the window opens the circuit.

# `record_result`

```elixir
@spec record_result(String.t(), term()) :: :ok
```

Records the result of a request using `should_melt?/1` logic.

Pass the raw result from Req (`{:ok, %Req.Response{}}` or `{:error, reason}`).

# `record_success`

```elixir
@spec record_success(String.t()) :: :ok
```

Records a successful request. Success prevents further melts.

# `reset`

```elixir
@spec reset(String.t()) :: :ok | {:error, :not_found}
```

Resets a circuit breaker for an exchange.

# `reset!`

```elixir
@spec reset!(String.t()) :: :ok
```

Resets a circuit breaker, raising on error.

# `should_melt?`

```elixir
@spec should_melt?(term()) :: boolean()
```

Determines if a response should trip the circuit breaker.

Melts on: HTTP 500+, transport errors.
Does NOT melt on: HTTP 429, HTTP 4xx, successful responses.

# `status`

```elixir
@spec status(String.t()) :: :ok | :blown | :not_installed
```

Returns the status of a circuit breaker for an exchange.

- `:ok` — circuit closed, requests allowed
- `:blown` — circuit open, requests rejected
- `:not_installed` — no fuse yet (no requests made)

---

*Consult [api-reference.md](api-reference.md) for complete listing*