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 Open API docs link 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 Open API docs link 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 Open API docs link 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.

Note that this PUT request, corresponding to the Update a zone entry point ruleset Open API docs link 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).

Note that this PUT request, corresponding to the Update a zone entry point ruleset Open API docs link 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.

Note that this PUT request, corresponding to the Update a zone entry point ruleset Open API docs link 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