Skip to main content

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​

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.

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.

Parameters​

See plugin common configurations 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.

  • 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.