Skip to content

error-page.md

Latest commit

 

History

History
171 lines (140 loc) · 5.88 KB

error-page.md

File metadata and controls

171 lines (140 loc) · 5.88 KB
Raw
title error-page
keywords
Apache APISIX
API Gateway
Plugin
Error page
error-page
description The error-page Plugin customizes the HTTP error response body and content type for APISIX-generated error responses, such as when no route matches or when APISIX itself encounters an error.

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):

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:

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:

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:

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:

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:

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:

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.

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