# API Breaker Configuration

The `api-breaker` plugin opens a circuit after configured upstream failures, returns a controlled response, and allows new requests after a backoff interval.<!-- --> <!-- -->Configuration covers static settings and plugin parameters.

## Static Configurations[​](#static-configurations "Direct link to Static Configurations")

The gateway stores breaker counters in the `plugin-api-breaker` shared memory zone. Each gateway instance allocates `10m` by default. Increase the zone when a gateway instance must track a large number of host and path combinations.

Shared memory zones are sized when the gateway starts. A full restart is required after changing the size; a reload does not resize an existing zone.

* Host or Docker
* Kubernetes (Helm)

For host or Docker deployments, override the zone in the persistent gateway configuration:

config.yaml

```
nginx_config:

  http:

    lua_shared_dict:

      plugin-api-breaker: 20m
```

Restart the gateway for the change to take effect.

For the APISIX Helm chart, set:

values.yaml

```
apisix:

  nginx:

    luaSharedDicts:

      - name: plugin-api-breaker

        size: 20m
```

For the API7 Gateway Helm chart, set:

values.yaml

```
apisix:

  http:

    luaSharedDict:

      plugin-api-breaker: 20m
```

Apply the complete values file with the chart used by the gateway release:

```
helm upgrade <release-name> <chart-name> -n <namespace> -f values.yaml
```

## Parameters[​](#parameters "Direct link to Parameters")

See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) for configuration options available to all plugins.

* break\_response\_code

  integer

  required

  valid value:

  between 200 and 599 inclusive

  ***

  HTTP status code returned while the circuit is open.

* break\_response\_body

  string

  ***

  Response body returned while the circuit is open.

* break\_response\_headers

  array\[object]

  ***

  Response headers added while the circuit is open. These headers are added only when `break_response_body` is configured.

  * key

    string

    required

    valid value:

    at least 1 character

    ***

    Response header name.

  * value

    string

    required

    valid value:

    at least 1 character

    ***

    Response header value. Supports [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md).

* max\_breaker\_sec

  integer

  default: `300`

  valid value:

  greater than or equal to 3

  ***

  Maximum open-circuit interval in seconds. The interval starts at 2 seconds and doubles after repeated failure thresholds until it reaches this value.

* unhealthy

  object

  default: `{"http_statuses":[500],"failures":3}`

  ***

  Conditions that record upstream failures and open the circuit.

  * http\_statuses

    array\[integer]

    default: `[500]`

    valid value:

    one or more unique values between 500 and 599 inclusive

    ***

    Upstream response status codes counted as unhealthy.

  * failures

    integer

    default: `3`

    valid value:

    greater than or equal to 1

    ***

    Number of unhealthy responses required to open the circuit.

* healthy

  object

  default: `{"http_statuses":[200],"successes":3}`

  ***

  Conditions that clear accumulated failure state after matching healthy responses.

  * http\_statuses

    array\[integer]

    default: `[200]`

    valid value:

    one or more unique values between 200 and 499 inclusive

    ***

    Upstream response status codes counted as healthy.

  * successes

    integer

    default: `3`

    valid value:

    greater than or equal to 1

    ***

    Number of healthy responses required to clear the failure state.
