Configure the custom-response plug-in - API Gateway - Alibaba Cloud Documentation Center

The custom-response plug-in allows you to configure custom responses, including status codes, HTTP response headers, and HTTP response bodies. The custom-response plug-in can be used for mock responses, or to provide custom responses after a specific HTTP status code is determined. For example, you can use the plug-in to configure a custom response that is returned when a gateway throttling policy is triggered. This topic describes how to configure the custom-response plug-in.

Plug-in type

Transmission protocol-related plug-in.

Fields

Field	Data type	Required	Default value	Description
status_code	number	No	200	The custom HTTP status code returned.
headers	array of string	No	-	The custom headers in the HTTP response. Separate keys and values with equal signs (`=`).
body	string	No	-	The custom body in the HTTP response.
enable_on_status	array of number	No	-	The original status code that is matched to generate a custom response. If you do not specify this field, the system does not determine the original status code.

Examples

Return a custom response in mock response scenarios

status_code: 200
headers:
- Content-Type=application/json
- Hello=World
body: "{\"hello\":\"world\"}"

The preceding configurations allow the following custom response to be returned:

HTTP/1.1 200 OK
Content-Type: application/json
Hello: World
Content-Length: 17

{"hello":"world"}

Return a custom response when throttling is triggered

enable_on_status: 
- 429
status_code: 302
headers:
- Location=https://example.com

When throttling is triggered, the HTTP status code 429 is returned in most cases. In this case, the following custom response is returned:

HTTP/1.1 302 Found
Location: https://example.com

This way, a browser-based 302 redirection mechanism is implemented to redirect the throttled user to another page, such as a static page uploaded to CDN.

If you want other status codes to be returned when throttling is triggered, configure the required fields by referring to the "Return a custom response in mock response scenarios" section.

Block requests for specific routes or domain names

Apply the following plug-in configurations to the route-a and route-b routes:

body: "{\"hello\":\"world\"}"

Apply the following plug-in configuration to the *.example.com and test.com domain names:

  enable_on_status: 
  - 429
  status_code: 200
  headers:
  - Content-Type=application/json
  body: "{\"errmsg\": \"rate limited\"}"

Note

The route-a and route-b routes are those specified when the gateway routes are created. If a client request matches one of the routes, the rules that are configured for the matched route take effect.
The *.example.com and test.com domain names are used to match domain names in requests. If a client request matches one of the domain names, the rules that are configured for the matched domain name take effect.
Rules that you configure take effect in sequence. If the first rule is matched, subsequent rules are ignored.