Example custom error rules

---

• Custom JSON response for all 5XX errors
• Dashboard
• API
• Custom HTML response with updated status code
• Dashboard
• API
• Custom HTML response for Cloudflare 1020 errors
• Dashboard
• API
• Custom error asset created from a URL
• Dashboard
• API

---

The provided examples use the following fields in their rule expressions:

• http.response.code (Response Status Code): Represents the HTTP status code returned to the client, either set by a Cloudflare product or returned by the origin server. Use this field to customize the response for error codes returned by the origin server or by a Cloudflare product such as a Worker.

• cf.response.1xxx_code: Contains the specific error code for Cloudflare-generated errors. This field will only work for Cloudflare-generated errors such as 52X and 1XXX.

Custom JSON response for all 5XX errors

This example configures a custom JSON error response for all 5XX errors (500-599) in a zone. The HTTP status code of the custom error response will be set to 530.

Dashboard

Custom error rule configuration:

• Name: Custom JSON response for all 5XX errors

• If incoming requests match > Custom filter expression:

  Field	Operator	Value	Logic
  Response Status Code	greater than or equal to	500	And
  Response Status Code	less than or equal to	599

  If using the Expression Editor:
  (http.response.code ge 500 and http.response.code le 599)

• Response type: JSON response

• Response code: 530

• JSON response: {"message": "A server error occurred."}

API

PUT /zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint

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.

Dashboard

Custom error rule configuration:

• Name: Custom HTML response for 500 errors

• If incoming requests match > Custom filter expression:

  Field	Operator	Value
  Response Status Code	equal to	500

  If using the Expression Editor:
  (http.response.code eq 500)

• Response type: HTML response

• Response code: 503

• HTML response:

  <!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>
  

API

PUT /zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint

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 Cloudflare 1020 errors

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

Dashboard

Custom error rule configuration:

• Name: Custom HTML response for 1020 errors

• If incoming requests match > Custom filter expression

  Use the Expression Editor:
  (cf.response.1xxx_code eq 1020)

• Response type: HTML response

• HTML response:

  <!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>
  

API

PUT /zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint

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 error asset created from a URL

This example configures a custom error rule returning a previously created custom error asset named 500_error_template for responses with a 500 HTTP status code.

Dashboard

Custom error rule configuration:

• Name: Serve asset for HTTP 500 errors

• If incoming requests match > Custom filter expression:

  Field	Operator	Value
  Response Status Code	equal to	500

  If using the Expression Editor:
  (http.response.code eq 500)

• Response type: Custom error asset

• Asset: 500_error_template

API

PUT /zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint

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.