The custom-response plug-in returns a custom HTTP response directly from the gateway. Use it to serve mock responses, return custom error pages, or redirect users when a specific upstream status code (such as HTTP 429 for throttling) is detected.
Use cases
| If you want to... | See |
|---|---|
| Return a static mock response for testing | Mock a response |
| Redirect throttled users to a fallback page | Redirect on throttling |
| Apply different response rules per route or domain | Scope to specific routes or domains |
How it works
The plug-in supports two response strategies:
Local response -- The gateway returns a custom status code, headers, and body directly. Typical use: mock responses and custom error pages.
Redirect response -- The gateway returns a
302status code to send the client to a different URL. Typical use: redirecting throttled users to a static fallback page on CDN.
When enable_on_status is set, the plug-in activates only if the upstream returns a matching status code. When enable_on_status is omitted, the plug-in returns the custom response unconditionally.
Rule evaluation order
When you configure multiple rules at the route and domain levels, the gateway evaluates them in order and applies the first match. After a rule matches, remaining rules are skipped.
Plug-in type
Transfer protocol-related plug-in.
Configuration fields
| Name | Data type | Required | Default | Description |
|---|---|---|---|---|
status_code | number | No | 200 | HTTP status code to return. |
headers | array of string | No | - | HTTP response headers. Use key=value format for each entry (for example, Content-Type=application/json). |
body | string | No | - | HTTP response body. |
enable_on_status | array of number | No | - | Upstream status codes that trigger the custom response. If omitted, the plug-in responds unconditionally. |
Configuration examples
Mock a response
Return a JSON response with custom headers:
status_code: 200
headers:
- Content-Type=application/json
- Hello=World
body: "{\"hello\":\"world\"}"This produces the following HTTP response:
HTTP/1.1 200 OK
Content-Type: application/json
Hello: World
Content-Length: 17
{"hello":"world"}Redirect on throttling
Redirect throttled requests to a static fallback page:
enable_on_status:
- 429
status_code: 302
headers:
- Location=https://example.comWhen throttling is triggered, HTTP status code 429 is returned in most cases. In this scenario, the gateway overrides the response:
HTTP/1.1 302 Found
Location: https://example.comThe browser follows the 302 redirect and loads the fallback page -- for example, a static page hosted on CDN.
If you want other status codes to be returned when throttling is triggered, configure the required fields as shown in Mock a response.
Scope to specific routes or domains
Configure the plug-in at the route or domain level.
Route-level -- applied to the route-a and route-b routes:
body: "{\"hello\":\"world\"}"Domain-level -- applied to the *.example.com and test.com domains:
enable_on_status:
- 429
status_code: 200
headers:
- Content-Type=application/json
body: "{\"errmsg\": \"rate limited\"}"The following evaluation rules apply:
route-aandroute-brefer to route names specified when creating gateway routes. If a request matches a route, the configuration for that route takes effect.*.example.comandtest.comare domain patterns. If a request matches a domain, the configuration for that domain takes effect.Rules are evaluated in order. Once a rule matches, the remaining rules are skipped.