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
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
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
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:
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:
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