1. Overview
API Gateway provides a circuit breaker for each API operation to protect the API operation in the event of abnormal backend performance. By default, if timeout occurs 1,000 times at the backend of an API operation within 30 seconds, the circuit breaker trips. The circuit stays open for 90 seconds, during which the following error is returned for all API requests: Status=503,X-Ca-Error-Code=D503CB. After 90 seconds, the circuit breaker allows a limited number of concurrent API requests to pass through. If these requests are successful, the circuit closes and API requests can be properly handled again.
You can also bind a plug-in of the Circuit Breaker type to an API operation to customize the configurations of its circuit breaker. Notice that plug-ins of the Circuit Breaker type take effect only for API operations on dedicated instances. You can customize the following configurations of a circuit breaker:
- The condition under which the circuit breaker trips. You can specify that the circuit breaker trips after the number of occurrences of timeout, or the number of occurrences of a specified error, at the backend reaches a threshold within a specified period of time.
- The time window during which the number of occurrences of timeout, or the number of occurrences of a specified error, at the backend is checked by the circuit breaker to determine whether to trip.
- The period of time during which the circuit breaker stays open after it trips.
- The backend to which API requests are directed when the circuit is open.
2. Configurations
Plug-ins of the Circuit Breaker type take effect only for API operations on dedicated instances. If you bind a plug-in of the Circuit Breaker type to an API operation in a shared instance, the circuit breaker still uses the default configurations.
2.1. Specify that the circuit breaker trips after the number of occurrences of timeout at the backend reaches a threshold
When you configure a plug-in of the Circuit Breaker type, you can specify that the circuit breaker trips after the number of occurrences of timeout at the backend reaches a threshold within a specified period of time. Specify the parameters in the following code snippet:
timeoutThreshold: 15 # The threshold of the number of occurrences of timeout at the backend.
windowInSeconds: 30 # The time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15 # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend: # The backend to which API requests are directed when the circuit is open.
type: mock
statusCode: 418
As shown in the code snippet, you can specify the following parameters:
timeoutThreshold
: the threshold of the number of occurrences of timeout at the backend. If this threshold is reached, the circuit breaker trips. The maximum value of this parameter is 5000. We recommend that you specify an appropriate value. If the value is too small, the circuit breaker trips after timeout occurs only several times.windowInSeconds
: the time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip. Valid values: 10 to 90. Unit: seconds.openTimeoutSeconds
: the period of time during which the circuit breaker stays open after it trips. Valid values: 15 to 300. Unit: seconds.downgradeBackend
: optional. The backend to which API requests are directed when the circuit is open.
2.2. Specify that the circuit breaker trips after the number of occurrences of a specified error at the backend reaches a threshold
When you configure a plug-in of the Circuit Breaker type, you can specify that the circuit breaker trips after the number of occurrences of a specified error at the backend reaches a threshold within a specified period of time. Specify the parameters in the following code snippet:
errorCondition: "$StatusCode == 503" # The conditional expression that specifies the error whose number of occurrences is checked by the circuit breaker to determine whether to trip.
errorThreshold: 1000 # The threshold of the number of occurrences of the specified error.
windowInSeconds: 30 # The time window during which the number of occurrences of the specified error at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15 # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend: # The backend to which API requests are directed when the circuit is open.
type: "HTTP"
address: "http://api.foo.com"
path: "/system-busy.json"
method: GET
errorCondition
: the conditional expression that specifies the error whose number of occurrences is checked by the circuit breaker to determine whether to trip. You can use the$StatusCode
and$LatencySeconds
variables.- If you specify a conditional expression as
$StatusCode = 503 or $StatusCode = 504
, the circuit breaker checks the total number of occurrences of HTTP status codes 503 and 504. - If you specify a conditional expression as
$LatancySeconds > 30
, the circuit breaker checks the total number of occurrences of timeout that is greater than 30 seconds.
- If you specify a conditional expression as
errorThreshold
: the threshold of the number of occurrences of the specified error.windowInSeconds
: the time window during which the number of occurrences of the specified error at the backend is checked by the circuit breaker to determine whether to trip. Valid values: 10 to 90. Unit: seconds.openTimeoutSeconds
: the period of time during which the circuit breaker stays open after it trips. Valid values: 15 to 300. Unit: seconds.downgradeBackend
: optional. The backend to which API requests are directed when the circuit is open.
3. Configure the backend to which API requests are directed when the circuit is open
You can specify the downgradeBackend
parameter to configure a backend to which API requests are directed when the circuit is open. Configurations of the backend must be consistent with the OpenAPI specification files that are imported to API Gateway. For more information, see Create APIs By Importing Swagger. You can configure the following types of backends by using the samples:
- HTTP
---
backend:
type: HTTP
address: "http://10.10.100.2:8000"
path: "/users/{userId}"
method: GET
timeout: 7000
- HTTP-VPC
---
backend:
type: HTTP-VPC
vpcAccessName: vpcAccess1
path: "/users/{userId}"
method: GET
timeout: 10000
- Function Compute
---
backend:
type: FC
fcRegion: cn-shanghai
serviceName: fcService
functionName: fcFunction
arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"
- MOCK
---
backend:
type: MOCK
mockResult: "mock resul sample"
mockStatusCode: 200
mockHeaders:
- name: Content-Type
value: text-plain
- name: Content-Language
value: zhCN
4. Error codes
Error code | HTTP status code | Error message | Description |
D503BB | 503 | Backend circuit breaker busy | The error message returned because the API operation is protected by its circuit breaker. |
D503CB | 503 | Backend circuit breaker open, ${Reason} | The error message returned because the circuit of the API operation is open. Test API calls after you check the backend performance of the API operation. |
5. Limits
- Plug-ins of the Circuit Breaker type take effect only for API operations on dedicated instances.
- Each conditional expression can contain a maximum of 512 characters.
- For each plug-in of the Circuit Breaker type, you can configure a maximum of 16,380 bytes of metadata.