Skip to main content

error-page

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.

Example​

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 "http://127.0.0.1:9180/apisix/admin/plugin_metadata/error_page" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -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 "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "uri": "/*",
    "id": "error-page-route",
    "plugins": {
      "serverless-post-function": {
        "functions": [
          "return function (conf, ctx)
              local core = require(\"apisix.core\")
              core.response.exit(404)
          end"
        ]
      },
      "error_page": {}
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 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 "http://127.0.0.1:9080/get"

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

<html>
  <head>
    <title>404</title>
  </head>
  <body>
    <center>
      <h1>404 not found</h1>
    </center>
    <hr>
    <center>API7 Entreprise Edition</center>
  </body>
</html>