Skip to content
Cloudflare Docs

Changelog

New updates and improvements at Cloudflare. Subscribe to RSS

hero image
← Back to all posts

Custom Errors (beta): Stored Assets & Account-level Rules

Feb 11, 2025, 11:00 AM
Rules

Cloudflare introduces Custom Errors (beta), building on Custom Error Responses with new asset storage capabilities. This update allows users to store externally hosted error pages at Cloudflare edge and reference them in custom error rules, eliminating the need to supply inline content.

New capabilities:

  • Custom error assets – Fetch and store external error pages at the edge for use in error responses.
  • Account-Level custom errors – Define error handling rules and assets at the account level for consistency across multiple zones. Zone-level rules take precedence over account-level ones, and assets are not shared between levels.

To store an external error page on the Cloudflare global network, submit a POST request to create an asset:

Terminal window
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '{
  "name": "maintenance",
  "description": "Maintenance template page",
  "url": "https://example.com/"
}'

Then, reference the stored asset in a custom error rule:

Terminal window
curl --request PUT \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom_errors/entrypoint" \
--header "Authorization: Bearer <API_TOKEN>" \
--header 'Content-Type: application/json' \
--data '{
  "rules": [
    {
      "action": "serve_error",
      "action_parameters": {
        "asset_name": "maintenance",
        "content_type": "text/html",
        "status_code": 503
      },
      "enabled": true,
      "expression": "http.request.uri.path contains \"error\""
    }
  ]
}'