Error Page

The error-page plugin customizes gateway-generated 404, 500, 502, and 503 responses without modifying responses returned by upstream services.

The error-page plugin customizes gateway-generated 404, 500, 502, and 503 responses. It does not modify responses returned by upstream services.

Enable the Plugin

API7 Gateway loads error-page by default. In APISIX, load the plugin in the gateway static configuration before configuring its metadata.

Keep the existing plugin list in config.yaml and add error-page:

config.yaml

plugins:
  # Keep the existing plugin list.
  - error-page

Reload APISIX for the change to take effect.

The APISIX Helm chart value apisix.plugins replaces the loaded plugin list. Start from the complete list used by the gateway, add error-page, and keep the other plugins unchanged:

values.yaml

apisix:
  plugins:
    # Keep the complete plugin list used by the gateway.
    - error-page

Apply the values file with the APISIX Helm chart.

Example

Customize Error Page

The example demonstrates how to customize a gateway-generated 404 response with plugin metadata.

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>Gateway</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 gateways 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.

Configure the plugin metadata and create a route with the serverless-post-function and error-page plugins:

adc.yaml

plugin_metadata:
  error-page:
    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>Gateway</center>\n  </body>\n</html>"
      content_type: text/html
services:
  - name: error-page-service
    routes:
      - name: error-page-route
        uris:
          - /*
        plugins:
          serverless-post-function:
            functions:
              - |
                return function (conf, ctx)
                    local core = require("apisix.core")
                    core.response.exit(404)
                end
          error-page: {}
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

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

❷ Enable error-page to return the customized error page.

Synchronize the configuration to the gateway:

adc sync -f adc.yaml

Create a route with the serverless-post-function and error-page plugins:

error-page-ic.yaml

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  type: ExternalName
  externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: error-page-plugin-config
spec:
  plugins:
    - name: serverless-post-function
      config:
        functions:
          - |
            return function (conf, ctx)
                local core = require("apisix.core")
                core.response.exit(404)
            end
    - name: error-page
      config: {}
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: error-page-route
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: error-page-plugin-config
      backendRefs:
        - name: httpbin-external-domain
          port: 80

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

❷ Enable error-page to return the customized error page.

Create a route with the serverless-post-function and error-page plugins:

error-page-ic.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: aic
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: error-page-route
spec:
  ingressClassName: apisix
  http:
    - name: error-page-route
      match:
        paths:
          - /*
      upstreams:
      - name: httpbin-external-domain
      plugins:
      - name: serverless-post-function
        enable: true
        config:
          functions:
            - |
              return function (conf, ctx)
                  local core = require("apisix.core")
                  core.response.exit(404)
              end
      - name: error-page
        enable: true
        config: {}

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

❷ Enable error-page to return the customized error page.

Update your GatewayProxy manifest to configure the error-page plugin metadata:

gatewayproxy.yaml

apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
  namespace: aic
  name: apisix-config
spec:
  provider:
    type: ControlPlane
    controlPlane:
      # ...
      # your control plane connection configuration
  pluginMetadata:
    error-page:
      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>Gateway</center>\n  </body>\n</html>"
        content_type: text/html

Apply the configuration to your cluster:

kubectl apply -f gatewayproxy.yaml -f error-page-ic.yaml

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>Gateway</center>
  </body>
</html>