Flow control and circuit breaking

Flow control limits the request rate of an API, while circuit breaking fails fast when the backend keeps erroring, preventing failures from spreading. Both types of rules run at the gateway based on Sentinel, are isolated by environment, and are pushed to the gateway dynamically without restart.

Entry

Security Management → Flow control rules. The page contains four tabs:

Tab	Purpose
Flow control	QPS rate limit rules
Circuit breaking	Slow call, exception ratio, and exception count circuit breaking
API cache	Response cache rules, see API cache
IP access control	IP black/whitelist, see IP access control and WAF

Flow control

List fields

Column	Description
Rule ID	Rate limit rule ID
Rule name	A recognizable name
QPS threshold	Number of requests allowed per second
Bound APIs	Number of APIs bound to the rule
Created by	Rule creator
Modified time	Most recent update time

The list supports filtering by rule name, creator, and environment.

Create a rate limit rule

1. Go to the "Flow control" tab;
2. Click "New";
3. Select the environment. The environment cannot be changed after creation;
4. Enter a rule name;
5. Enter the QPS threshold, i.e. the maximum number of requests allowed per second;
6. After saving, click "Bind" on the rule and select the APIs to rate limit.

API binding is isolated by environment: a rule can only bind APIs in the same environment. A rule takes effect only after APIs are bound.

Execution logic

• The gateway uses the route ID as the Sentinel resource identifier; each release snapshot of an API in an environment corresponds to one resource;
• The rate limit threshold applies over a 1-second statistical window; only QPS mode is supported;
• When the threshold is exceeded, the gateway returns HTTP 429 with business code 40429 and the message "Client request frequency is too high, the API has been rate limited";
• Rate-limited requests are written to the call log and marked as failed;
• Rules are written to Redis; after a change on the admin side, gateway rule snapshots are refreshed incrementally through events, keeping multiple instances consistent.

Circuit breaking

Three circuit breaking strategies

Strategy	degradeType	Trigger condition	Key parameters
Slow call ratio	0	Slow call share exceeds the threshold	Max response time (RT), ratio threshold, time window, minimum request count, circuit breaking duration
Exception ratio	1	Exception request share exceeds the threshold	Ratio threshold (0.0–1.0), time window, minimum request count, circuit breaking duration
Exception count	2	Number of exceptions in the time window exceeds the threshold	Exception count threshold, time window, minimum request count, circuit breaking duration

Create a circuit breaking rule

1. Go to the "Circuit breaking" tab;
2. Click "New";
3. Select the environment and enter a rule name;
4. Select a circuit breaking strategy; the page shows the corresponding fields for that strategy;
5. Enter the thresholds:
   • Slow call ratio: max response time (milliseconds) and ratio threshold (0.0–1.0);
   • Exception ratio: ratio threshold (0.0–1.0);
   • Exception count: number of exceptions within the time window;
6. Enter the time window (seconds), minimum request count, and circuit breaking duration (seconds);
7. Save and bind APIs.

The minimum request count avoids false positives from small samples: circuit breaking is not triggered when the number of requests in the time window is insufficient.

Execution logic

• After circuit breaking is triggered, the gateway returns HTTP 503 with business code 40503 and the message "The current service is abnormal, the API has been circuit broken";
• When the circuit breaking duration ends, the circuit enters the half-open state, and Sentinel decides whether to recover or continue breaking based on the results of allowed requests;
• Circuit breaking rules and rate limit rules can be bound to the same API at the same time; requests pass the rate limit check first and then the circuit breaker;
• Rule changes are refreshed incrementally through Redis events, so the gateway does not need a restart; rule caches have an expiration time, so expired rules are not retained indefinitely when the admin side is unavailable.

Rule scope and precedence

• Flow control and circuit breaking both act on the API + environment dimension and do not distinguish caller apps;
• APIs not bound to any rule are unaffected by flow control;
• Rules apply only to traffic in the environment where they were bound; after switching environments, bind them again;
• The gateway's admin backend routes do not pass through open API flow control.

Operations recommendations

Scenario	Recommendation
An API is saturated by burst traffic	Start with a QPS slightly above the normal peak, then tighten gradually while watching the logs
Occasional downstream timeouts	Use slow call ratio circuit breaking with an RT threshold near P99
Persistent downstream errors	Use exception ratio or exception count circuit breaking together with alert rules
Rules are not taking effect	Check the environment, the number of bound APIs, and whether the gateway received the rule refresh event
Rate limiting hits legitimate calls	Confirm that the QPS unit is "per second" and check the per-environment configuration

Relationship to other governance capabilities

• Alert rules: configure alerts for timeouts, HTTP status codes, error rates, and consecutive failures; see alert rules and records;
• API cache: cache hits reduce downstream pressure, but rate-limited requests do not reach the cache check;
• IP access control: IP blocking happens before and after authentication and is independent of flow control;
• Quota: subscription quotas limit daily call volume per app and take effect in combination with API-level QPS rate limiting.