Skip to main content

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:

StateBehavior
ClosedRequests reach the upstream. Responses with a configured unhealthy status increment the failure count.
OpenRequests 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.
RecoveryAfter 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:

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.

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
}
}
}'

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