Skip to content
Cloudflare Docs
DirectoryAPISDKsChangelog

Example custom error rules

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.

Custom error rule configuration:

  • Name: Custom JSON response for all 5XX errors

  • If incoming requests match > Custom filter expression:

    FieldOperatorValueLogic
    Response Status Codegreater than or equal to500And
    Response Status Codeless than or equal to599

    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."}

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:

    FieldOperatorValue
    Response Status Codeequal to500

    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>
    "rules": [
    {
    "ref": "html_response_500_to_503",
    "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
    }
    ]
    }'
"rules": [
{
"ref": "html_response_cf_1020",
"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
}
]
}'
"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 in the Terraform documentation.

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.