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:
Use the List zone rulesets operation to check if there is already a ruleset for the
http_custom_errors
phase at the zone level.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