# API Breaker

The `api-breaker` plugin provides passive circuit breaking for an upstream service. It evaluates the final upstream response status, stops requests from reaching the upstream after a configured failure threshold, and returns a controlled response while the circuit is open.

This behavior reduces traffic to a failing service and gives clients a predictable response during timed backoff intervals.

## Circuit Breaker Behavior[​](#circuit-breaker-behavior "Direct link to Circuit Breaker Behavior")

The circuit moves through these states based on live request traffic:

| State    | Behavior                                                                                                                                                                                                                                                        |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Closed   | Requests reach the upstream. Responses with a configured unhealthy status increment the failure count.                                                                                                                                                          |
| Open     | Requests receive the configured break response without reaching the upstream. The first open interval is two seconds; after further failure thresholds, later intervals double up to the configured maximum.                                                    |
| Recovery | After an open interval expires, requests reach the upstream again. Configured healthy responses increment the success count. Reaching the configured success threshold clears the failure state, while another unhealthy response resets the recovery progress. |

Matching unhealthy responses accumulate until recovery completes; they do not need to be consecutive or occur within a time window. Responses whose status is in neither the healthy nor unhealthy list do not change the counters.

Breaker state is local to each gateway instance and shared by requests with the same host and normalized path. Query strings, route and service IDs, and upstream node IDs do not create separate circuits. The plugin does not run active health probes.

## Example[​](#example "Direct link to Example")

The example opens a circuit after a controlled upstream failure and verifies that new requests reach the upstream after the backoff interval.

### Open and Recover a Circuit[​](#open-and-recover-a-circuit "Direct link to Open and Recover a Circuit")

The Docker-based setup uses a test upstream that initially returns `500 Internal Server Error` and can be switched to return `200 OK`. It requires a running APISIX or API7 Gateway container that can join a Docker network.

Create and enter a working directory for the example:

```
mkdir api-breaker-example

cd api-breaker-example
```

Create the following Python script for the test upstream:

breaker-upstream.py

```
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer





healthy = False





class Handler(BaseHTTPRequestHandler):

    protocol_version = "HTTP/1.1"



    def do_GET(self):

        if self.path != "/breaker-test":

            self.send_error(404)

            return



        status = 200 if healthy else 500

        body = b"upstream healthy\n" if healthy else b"upstream unhealthy\n"



        self.send_response(status)

        self.send_header("Content-Type", "text/plain")

        self.send_header("Content-Length", str(len(body)))

        self.end_headers()

        self.wfile.write(body)



    def do_PUT(self):

        global healthy



        if self.path == "/healthy":

            healthy = True

        elif self.path == "/unhealthy":

            healthy = False

        else:

            self.send_error(404)

            return



        self.send_response(204)

        self.send_header("Content-Length", "0")

        self.end_headers()



    def log_message(self, *_):

        pass





ThreadingHTTPServer(("0.0.0.0", 8000), Handler).serve_forever()
```

Set `GATEWAY_CONTAINER` to the running APISIX or API7 Gateway container. Create a dedicated network and connect the gateway to it:

```
export GATEWAY_CONTAINER=replace-with-gateway-container-name



docker network create gateway-api-breaker-net

docker network connect gateway-api-breaker-net "$GATEWAY_CONTAINER"
```

Start the test upstream and expose its control endpoint only on the local machine:

```
docker run -d \

  --name api-breaker-upstream \

  --network gateway-api-breaker-net \

  -p "127.0.0.1:18081:8000" \

  -v "$PWD/breaker-upstream.py:/breaker-upstream.py:ro" \

  python:3.13.15-alpine3.24 \

  python -u /breaker-upstream.py
```

Configure the circuit to open after one `500` response. The example uses one required healthy response so that recovery is visible immediately after the open interval expires.

If Admin API authentication is enabled, export an admin-role key as `ADMIN_API_KEY` before using the Admin API tab.

* Admin API
* ADC

Create the route:

```
curl "http://127.0.0.1:9180/apisix/admin/routes/api-breaker-route" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "uri": "/breaker-test",

    "plugins": {

      "api-breaker": {

        "break_response_code": 503,

        "break_response_body": "{\"message\":\"circuit open\"}",

        "break_response_headers": [

          {

            "key": "Content-Type",

            "value": "application/json"

          },

          {

            "key": "X-Circuit-Status",

            "value": "open"

          }

        ],

        "max_breaker_sec": 3,

        "unhealthy": {

          "http_statuses": [500],

          "failures": 1

        },

        "healthy": {

          "http_statuses": [200],

          "successes": 1

        }

      }

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "api-breaker-upstream:8000": 1

      }

    }

  }'
```

Configure ADC to connect to the target backend. The remaining ADC commands read the connection settings from these environment variables:

* APISIX
* API7 Gateway

If Admin API authentication is enabled, export an admin-role key as `ADMIN_API_KEY` before configuring ADC.

```
export ADC_BACKEND=apisix

export ADC_SERVER="http://127.0.0.1:9180"

export ADC_TOKEN="${ADMIN_API_KEY}"
```

```
export ADC_BACKEND=api7ee

export ADC_SERVER="https://{DASHBOARD_ADDR}"

export ADC_TOKEN="{DASHBOARD_TOKEN}"

export ADC_GATEWAY_GROUP="{GATEWAY_GROUP}"
```

Create the service and route:

adc.yaml

```
services:

  - name: api-breaker-service

    labels:

      docs-example: api-breaker

    routes:

      - name: api-breaker-route

        uris:

          - /breaker-test

        plugins:

          api-breaker:

            break_response_code: 503

            break_response_body: '{"message":"circuit open"}'

            break_response_headers:

              - key: Content-Type

                value: application/json

              - key: X-Circuit-Status

                value: open

            max_breaker_sec: 3

            unhealthy:

              http_statuses:

                - 500

              failures: 1

            healthy:

              http_statuses:

                - 200

              successes: 1

    upstream:

      type: roundrobin

      nodes:

        - host: api-breaker-upstream

          port: 8000

          weight: 1
```

Preview the changes and confirm that they only affect resources for this example:

```
adc diff -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=api-breaker
```

Review `diff.yaml`, then synchronize the labeled service:

```
adc sync -f adc.yaml \

  --include-resource-type service \

  --label-selector docs-example=api-breaker
```

Set the upstream to its unhealthy response, then send the first request. The request reaches the upstream and records the `500` response:

```
curl "http://127.0.0.1:18081/unhealthy" -X PUT

curl --include "http://127.0.0.1:9080/breaker-test"
```

The upstream failure is returned to the client:

```
HTTP/1.1 500 Internal Server Error

...

upstream unhealthy
```

Send another request immediately. The open circuit returns the configured response without contacting the upstream:

```
curl --include "http://127.0.0.1:9080/breaker-test"
```

The open circuit returns:

```
HTTP/1.1 503 Service Temporarily Unavailable

Content-Type: application/json

X-Circuit-Status: open

...

{"message":"circuit open"}
```

Switch the upstream to its healthy response, then wait for the initial two-second open interval to expire:

```
curl "http://127.0.0.1:18081/healthy" -X PUT

sleep 3
```

Send another request. It reaches the upstream, receives `200`, and clears the breaker state because one successful response is enough in this example:

```
curl --include "http://127.0.0.1:9080/breaker-test"
```

The recovered request returns:

```
HTTP/1.1 200 OK

...

upstream healthy
```
