Custom Error Pages

Custom error responses with template variable support

Overview

Custom error pages replace default error responses with branded, user-friendly content in any format (HTML, JSON, XML). They are served when HTTP error status codes (4xx, 5xx) are detected, when transport errors occur, or when policies block requests. Error pages support static content, template variables, and dynamic content fetched via callbacks.

Capabilities

  • Match by specific status codes or catch-all for any error
  • Custom HTML, JSON, or base64-encoded bodies
  • Template variables for dynamic content: status_code, error, request.url, request.method, context
  • Callback-based error pages fetched from external services
  • Per-status configuration with custom headers and status code overrides
  • Configurable default_content_type at the origin level

Example

Serve a JSON error page for 404 and 500 responses:

proxy:
  http_bind_port: 8080

origins:
  "app.example.com":
    action:
      type: proxy
      url: https://test.sbproxy.dev
    error_pages:
      - status:
          - 404
        content_type: application/json
        json_body:
          error: Not Found
          status: 404
      - status:
          - 500
          - 502
          - 503
        content_type: text/html
        body: "<h1>Service Unavailable</h1><p>Please try again later.</p>"

Test it:

curl -H "Host: app.example.com" http://localhost:8080/
← PreviousSessionNext →Examples