Skip to main content


The error-page plugin allows customizing the error page served when APISIX throws 404, 500, 502, and 503 exceptions. Note that it does not allow customizing the error page if the exceptions are thrown by upstream services.


Customize Error Page

The example demonstrates how you can customize the error page by configuring the customized content on plugin metadata and serve the error page when a 404 error is encountered.

Configure the plugin metadata for customized error page:

curl "" -X PUT \
-d '{
"enable": true,
"error_404": {
"body": "<html>\n <head>\n <title>404</title>\n </head>\n <body>\n <center>\n <h1>404 not found</h1>\n </center>\n <hr>\n <center>API7 Entreprise Edition</center>\n </body>\n</html>",
"content-type": "text/html"

To demonstrate the function of the plugin, create a route with the serverless-post-function plugin, which returns a 404 error code from the APISIX side for all requests to the route:

curl "" -X PUT \
-d '{
"uri": "/*",
"id": "error-page-route",
"plugins": {
"serverless-post-function": {
"functions": [
"return function (conf, ctx)
local core = require(\"apisix.core\")
"error_page": {}
"upstream": {
"nodes": {
"": 1
"type": "roundrobin"

❶ return a 404 status code for all requests to the route.

❷ enable error_page to return the customized error page.

Send a request to the route:

curl -i ""

You should see an HTTP/1.1 404 Not Found response with the following response body:

<h1>404 not found</h1>
<center>API7 Entreprise Edition</center>
</html> Logo

API Management for Modern Architectures with Edge, API Gateway, Kubernetes, and Service Mesh.


API7 Cloud

SOC2 Type IRed Herring

Copyright © APISEVEN Ltd. 2019 – 2024. Apache, Apache APISIX, APISIX, and associated open source project names are trademarks of the

Apache Software Foundation