Cloudflare Docs
Rules
Cloudflare Docs
Rules
GitHub icon
Visit Rules on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Rules
  3. Custom error responses
  4. Create via API

Create a custom error response via API

Configure custom error responses as rules belonging to the http_custom_errors phase. Use the Rulesets API to create custom error responses via API.

​​ Basic rule settings

When creating a custom error response via API, make sure you:

  • Set the rule action to serve_error.
  • Define the parameters in the action_parameters field according to response type.
  • Deploy the custom error response rule to the http_custom_errors phase at the zone level.

The first rule in the http_custom_errors phase ruleset that matches will be applied. No other rules in the ruleset will be matched or applied.

​​ Procedure

Follow this workflow to create a custom error response rule for a given zone via API:

  1. Use the List zone rulesets operation to check if there is already a ruleset for the http_custom_errors phase at the zone level.

  2. If the phase ruleset does not exist, create it using the Update a zone entry point ruleset operation, which allows you to create a ruleset if it does not exist and update all the rules in the ruleset. Create the ruleset in the http_custom_errors phase.

    If the phase ruleset already exists, use the Update a zone entry point ruleset operation to replace all the rules in the ruleset, or the Add rule to ruleset operation to add a rule to the existing rules in the ruleset.

​​ Example API calls

​​ Custom JSON response for all Cloudflare 1xxx errors

This example configures a custom JSON error response for all Cloudflare 1xxx errors in the zone with ID {zone_id}. The HTTP status code of the custom error response will be set to 530.


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": {
        "content": "{\"message\": \"A 1xxx error occurred.\"}",
        "content_type": "application/json",
        "status_code": 530
      },
      "expression": "cf.response.error_type eq \"1xxx\"",
      "enabled": true
    }
  ]
}'

Note that this PUT request, corresponding to the Update a zone entry point ruleset operation, replaces any existing rules in the http_custom_errors phase entry point ruleset.

​​ Custom HTML response for 1020 errors

This example configures a custom HTML error response for Cloudflare error 1020 (Access Denied).


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": {
        "content": "<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Access denied</title></head><body><h1>You do not have access to this page</h1><p>Contact us if you think this is an error.</p></body></html>",
        "content_type": "text/html"
      },
      "expression": "cf.response.1xxx_code eq 1020",
      "enabled": true
    }
  ]
}'

Note that this PUT request, corresponding to the Update a zone entry point ruleset operation, replaces any existing rules in the http_custom_errors phase entry point ruleset.

​​ Custom HTML response with updated status code

This example configures a custom HTML error response for responses with a 500 HTTP status code, and redefines the response status code to 503.


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": {
        "content": "<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>Application unavailable</title></head><body><h1>Application temporarily unavailable</h1><p>Please try again later.</p></body></html>",
        "content_type": "text/html",
        "status_code": 503
      },
      "expression": "http.response.code eq 500",
      "enabled": true
    }
  ]
}'

Note that this PUT request, corresponding to the Update a zone entry point ruleset operation, replaces any existing rules in the http_custom_errors phase entry point ruleset.

​​ ​​Required API token permissions

The API token used in API requests to manage custom error responses must have at least the following permission:

  • Custom Error Rules > Edit