This custom plugin allows APISIX to return a custom error page for status codes 404, 500, 502 and 503.
For example, it allows to replace the default response for 404:
{"error_msg":"404 Route Not Found"}To install custom plugins in APISIX there are 2 methods:
- placing them alongside other built-in plugins, in
${APISIX_INSTALL_DIRECTORY}/apisix/plugins/(by default/usr/local/apisix/apisix/plugins/); - placing them in a custom directory and setting
apisix.extra_lua_pathto point that directory, inconfig.yaml.
This plugin can be configured for Routes or Global Rules.
| Name | Type | Required | Default | Valid values | Description |
|---|---|---|---|---|---|
| enable | boolean | False | false |
If true, enable the plugin. | |
| error_404 | object | False | Error page to return when APISIX returns 404 status codes. | ||
| error_404.body | string | False | <html> <head><title>404 Not Found</title></head> <body> <center><h1>404 Not Found</h1></center> <hr><center>APISIX</center> </html> |
Response body. | |
| error_404.content-type | string | False | text/html |
Response content type. | |
| error_500 | object | False | Error page to return when APISIX returns 500 status codes. | ||
| error_500.body | string | False | <html> <head><title>500 Internal Server Error</title></head> <body> <center><h1>500 Internal Server Error</h1></center> <hr><center>APISIX</center> </html> |
Response body. | |
| error_500.content-type | string | False | text/html |
Response content type. | |
| error_502 | object | False | Error page to return when APISIX returns 502 status codes. | ||
| error_502.body | string | False | <html> <head><title>502 Bad Gateway</title></head> <body> <center><h1>502 Bad Gateway</h1></center> <hr><center>APISIX</center> </html> |
Response body. | |
| error_502.content-type | string | False | text/html |
Response content type. | |
| error_503 | object | False | Error page to return when APISIX returns 503 status codes. | ||
| error_503.body | string | False | <html> <head><title>503 Service Unavailable</title></head> <body> <center><h1>503 Service Unavailable</h1></center> <hr><center>APISIX</center> </html> |
Response body. | |
| error_503.content-type | string | False | text/html |
Response content type. |
Important
Plugin metadata set global values, shared accross all plugin instances. For example, if we have 2 different routes with error-page plugin enabled, plugin_metadata values will be the same for both of them.
The examples below enable error-page plugin globally. With these configurations, APISIX will return a custom error message for status codes 404 and 500, on every route (even on undefined ones).
Configure the plugin metadata:
curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page -H "X-API-KEY: $admin_key" -X PUT -d '
{
"enable": true,
"error_404": {
"body": "{\"status_code\":404,\"error\":\"Not Found\"}",
"content-type": "application/json"
},
"error_500": {
"body": "{\"status_code\":500,\"error\":\"API Gateway Error\"}",
"content-type": "application/json"
},
}'Enable the plugin globally, using global rules:
curl http://127.0.0.1:9180/apisix/admin/global_rules/error-page -H "X-API-KEY: $admin_key" -X PUT -d '
{
"plugins": {
"error-page": {}
}
}'Configure the plugin metadata:
plugin_metadata:
- id: error-page
enable: true
error_404:
body: |
{
"status_code": 404,
"error": "Not Found"
}
content-type: "application/json"
error_500:
body: |
{
"status_code": 500,
"error": "API Gateway Error"
}
content-type: "application/json"Enable the plugin globally, using global rules:
global_rules:
- id: generic_error_page
plugins:
error-page: {}Send some request to test error pages:
-
Route not defined (overrides default error page for 404):
curl -i "localhost:9080/unknown"Response:
HTTP/1.1 404 Not Found Content-Type: application/json Connection: keep-alive Server: APISIX/3.12.0 Content-Length: 49 { "status_code": 404, "error": "Not Found" } -
Status code 500 returned from APISIX:
curl -i "localhost:9080/apisix_status/500"Response:
HTTP/1.1 500 Internal Server Error Content-Type: application/json Connection: close Server: APISIX/3.12.0 Content-Length: 57 { "status_code": 500, "error": "API Gateway Error" }
Folder examples/ contains a simple example that shows how to setup APISIX locally on Docker, and load error-page plugin.
For more example ideas, have a look at github.com/mikyll/apisix-examples.
See apisix.yaml.
Run the following command to setup the example:
docker compose -f examples/apisix-docker-standalone/compose.yaml upRun test_routes.sh to send testing requests.