error-page - Apisix — ContextQMD

<head> <link rel="canonical" href="https://docs.api7.ai/hub/error-page" /> </head>

Description

The error-page Plugin customizes the response body and content type for HTTP error responses generated by APISIX itself (for example, when no route matches or when the upstream is unreachable). Responses from upstream services are not affected.

This Plugin uses Plugin metadata for global configuration and requires no per-route attributes. When enabled, it intercepts error responses and replaces their body with the configured content.

Plugin Metadata

There are no attributes to configure this Plugin on Routes, Services, or other resources. All configuration is done through Plugin metadata.

Name	Type	Required	Default	Description
enable	boolean	False	false	Set to `true` to enable the Plugin.
error_404	object	False		Custom error page for 404 responses.
error_404.body	string	False	Default HTML page	Response body for 404 responses.
error_404.content_type	string	False	text/html	Content type of the response body.
error_500	object	False		Custom error page for 500 responses.
error_500.body	string	False	Default HTML page	Response body for 500 responses.
error_500.content_type	string	False	text/html	Content type of the response body.
error_502	object	False		Custom error page for 502 responses.
error_502.body	string	False	Default HTML page	Response body for 502 responses.
error_502.content_type	string	False	text/html	Content type of the response body.
error_503	object	False		Custom error page for 503 responses.
error_503.body	string	False	Default HTML page	Response body for 503 responses.
error_503.content_type	string	False	text/html	Content type of the response body.

Enable Plugin

The error-page Plugin is disabled by default. To enable the Plugin, add it to your configuration file (conf/config.yaml):

yaml

plugins:
  - ...
  - error-page

Configure Plugin Metadata

:::note You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

bash

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

Configure the Plugin metadata to enable the Plugin and define custom error pages:

shell

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": "<html><body><h1>404 - Page Not Found</h1></body></html>",
        "content_type": "text/html"
    },
    "error_500": {
        "body": "<html><body><h1>500 - Internal Server Error</h1></body></html>",
        "content_type": "text/html"
    },
    "error_502": {
        "body": "<html><body><h1>502 - Bad Gateway</h1></body></html>",
        "content_type": "text/html"
    },
    "error_503": {
        "body": "<html><body><h1>503 - Service Unavailable</h1></body></html>",
        "content_type": "text/html"
    }
}'

You can also return JSON error responses by setting a custom content_type:

shell

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": "{\"code\": 404, \"message\": \"Resource not found\"}",
        "content_type": "application/json"
    },
    "error_500": {
        "body": "{\"code\": 500, \"message\": \"Internal server error\"}",
        "content_type": "application/json"
    }
}'

Since the Plugin uses global metadata, you also need to enable it on the routes where you want it to take effect. You can use a global rule to apply it to all routes:

shell

curl http://127.0.0.1:9180/apisix/admin/global_rules/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {
        "error-page": {}
    }
}'

Example usage

After configuring the Plugin and metadata as shown above, trigger a 404 error by accessing a non-existent route:

shell

curl -i http://127.0.0.1:9080/non-existent-path

HTTP/1.1 404 Not Found
Content-Type: text/html
...

<html><body><h1>404 - Page Not Found</h1></body></html>

Disable Plugin

To stop the Plugin from intercepting errors, delete the Plugin metadata:

shell

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page \
-H "X-API-KEY: $admin_key" -X DELETE

To remove the Plugin entirely from a route, delete it from the route's plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

shell

curl http://127.0.0.1:9180/apisix/admin/global_rules/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {}
}'