--- description: Example custom error rules for common error handling scenarios. title: Example custom error rules image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/rules/llms.txt > Use this file to discover all available pages before exploring further. # Example custom error rules Last updated Aug 25, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/rules/custom-errors/example-rules/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) The provided examples use the following fields in their rule expressions: - [`http.response.code`](https://developers.cloudflare.com/ruleset-engine/rules-language/fields/reference/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`](https://developers.cloudflare.com/ruleset-engine/rules-language/fields/reference/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](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/) and [1XXX](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/). ### 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`. **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."}`
Required API token permissions At least one of the following token permissions is required: - Response Compression Write - Config Settings Write - Dynamic URL Redirects Write - Cache Settings Write - Custom Errors Write - Origin Write - Managed headers Write - Zone Transform Rules Write - Mass URL Redirects Write - Magic Firewall Write - L4 DDoS Managed Ruleset Write - HTTP DDoS Managed Ruleset Write - Sanitize Write - Transform Rules Write - Select Configuration Write - Bot Management Write - Zone WAF Write - Account WAF Write - Account Rulesets Write - Logs Write - Logs Write
*Update a zone entry point rulesetbash* ```bash curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_custom_errors/entrypoint" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "ref": "json_response_for_5xx_errors", "action": "serve_error", "action_parameters": { "content": "{\"message\": \"A server error occurred.\"}", "content_type": "application/json", "status_code": 530 }, "expression": "http.response.code ge 500 and http.response.code lt 600", "enabled": true } ] }' ``` Use the `ref` field to get stable rule IDs across updates when using Terraform. Adding this field prevents Terraform from recreating the rule on changes. For more information, refer to [Troubleshooting](https://developers.cloudflare.com/terraform/troubleshooting/rule-id-changes/#how-to-keep-the-same-rule-id-between-modifications) in the Terraform documentation. This `PUT` request, corresponding to the [Update a zone entry point ruleset](https://developers.cloudflare.com/api/resources/rulesets/subresources/phases/methods/update/) 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`. **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**: ```txt Application unavailable

Application temporarily unavailable

Please try again later.

```
Required API token permissions At least one of the following token permissions is required: - Response Compression Write - Config Settings Write - Dynamic URL Redirects Write - Cache Settings Write - Custom Errors Write - Origin Write - Managed headers Write - Zone Transform Rules Write - Mass URL Redirects Write - Magic Firewall Write - L4 DDoS Managed Ruleset Write - HTTP DDoS Managed Ruleset Write - Sanitize Write - Transform Rules Write - Select Configuration Write - Bot Management Write - Zone WAF Write - Account WAF Write - Account Rulesets Write - Logs Write - Logs Write
*Update a zone entry point rulesetbash* ```bash curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_custom_errors/entrypoint" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "ref": "html_response_500_to_503", "action": "serve_error", "action_parameters": { "content": "Application unavailable

Application temporarily unavailable

Please try again later.

", "content_type": "text/html", "status_code": 503 }, "expression": "http.response.code eq 500", "enabled": true } ] }' ``` Use the `ref` field to get stable rule IDs across updates when using Terraform. Adding this field prevents Terraform from recreating the rule on changes. For more information, refer to [Troubleshooting](https://developers.cloudflare.com/terraform/troubleshooting/rule-id-changes/#how-to-keep-the-same-rule-id-between-modifications) in the Terraform documentation. This `PUT` request, corresponding to the [Update a zone entry point ruleset](https://developers.cloudflare.com/api/resources/rulesets/subresources/phases/methods/update/) 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](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1020/) (Access Denied). **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**: ```txt Access denied

You do not have access to this page

Contact us if you think this is an error.

```
Required API token permissions At least one of the following token permissions is required: - Response Compression Write - Config Settings Write - Dynamic URL Redirects Write - Cache Settings Write - Custom Errors Write - Origin Write - Managed headers Write - Zone Transform Rules Write - Mass URL Redirects Write - Magic Firewall Write - L4 DDoS Managed Ruleset Write - HTTP DDoS Managed Ruleset Write - Sanitize Write - Transform Rules Write - Select Configuration Write - Bot Management Write - Zone WAF Write - Account WAF Write - Account Rulesets Write - Logs Write - Logs Write
*Update a zone entry point rulesetbash* ```bash curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_custom_errors/entrypoint" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "ref": "html_response_cf_1020", "action": "serve_error", "action_parameters": { "content": "Access denied

You do not have access to this page

Contact us if you think this is an error.

", "content_type": "text/html" }, "expression": "cf.response.1xxx_code eq 1020", "enabled": true } ] }' ``` Use the `ref` field to get stable rule IDs across updates when using Terraform. Adding this field prevents Terraform from recreating the rule on changes. For more information, refer to [Troubleshooting](https://developers.cloudflare.com/terraform/troubleshooting/rule-id-changes/#how-to-keep-the-same-rule-id-between-modifications) in the Terraform documentation. This `PUT` request, corresponding to the [Update a zone entry point ruleset](https://developers.cloudflare.com/api/resources/rulesets/subresources/phases/methods/update/) 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. **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`
Required API token permissions At least one of the following token permissions is required: - Response Compression Write - Config Settings Write - Dynamic URL Redirects Write - Cache Settings Write - Custom Errors Write - Origin Write - Managed headers Write - Zone Transform Rules Write - Mass URL Redirects Write - Magic Firewall Write - L4 DDoS Managed Ruleset Write - HTTP DDoS Managed Ruleset Write - Sanitize Write - Transform Rules Write - Select Configuration Write - Bot Management Write - Zone WAF Write - Account WAF Write - Account Rulesets Write - Logs Write - Logs Write
*Update a zone entry point rulesetbash* ```bash curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_custom_errors/entrypoint" \ --request PUT \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "rules": [ { "ref": "serve_error_500_asset", "action": "serve_error", "action_parameters": { "asset_name": "500_error_template", "content_type": "text/html" }, "expression": "http.response.code eq 500", "enabled": true } ] }' ``` Use the `ref` field to get stable rule IDs across updates when using Terraform. Adding this field prevents Terraform from recreating the rule on changes. For more information, refer to [Troubleshooting](https://developers.cloudflare.com/terraform/troubleshooting/rule-id-changes/#how-to-keep-the-same-rule-id-between-modifications) in the Terraform documentation. This `PUT` request, corresponding to the [Update a zone entry point ruleset](https://developers.cloudflare.com/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/rules/custom-errors/example-rules/#page","headline":"Example custom error rules ยท Cloudflare Rules docs","description":"Example custom error rules for common error handling scenarios.","url":"https://developers.cloudflare.com/rules/custom-errors/example-rules/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-25","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```