自定义错误规则示例

提供的示例在其规则表达式中使用了以下字段：

http.response.code（响应状态代码）：表示返回给客户端的 HTTP 状态代码，可由 Cloudflare 产品设置，也可由源服务器返回。使用此字段可为源服务器或 Cloudflare 产品（例如 Worker）返回的错误代码自定义响应。
cf.response.1xxx_code：包含 Cloudflare 生成的错误的特定错误代码。此字段仅适用于 Cloudflare 生成的错误，例如 52X 和 1XXX。

所有 5XX 错误的自定义 JSON 响应

本示例为区域中的所有 5XX 错误（500-599）配置自定义 JSON 错误响应。自定义错误响应的 HTTP 状态代码将设置为 530。

自定义错误规则配置：

Name（名称）：所有 5XX 错误的自定义 JSON 响应
If incoming requests match（当传入请求匹配时）> Custom filter expression（自定义筛选表达式）：

字段运算符值逻辑

Response Status Code（响应状态代码） greater than or equal to 500 And

Response Status Code（响应状态代码） less than or equal to 599

如果使用表达式编辑器：
(http.response.code ge 500 and http.response.code le 599)
Response type（响应类型）：JSON response（JSON 响应）
Response code（响应代码）：530
JSON response（JSON 响应）：{"message": "A server error occurred."}

字段	运算符	值	逻辑
Response Status Code（响应状态代码）	greater than or equal to	`500`	And
Response Status Code（响应状态代码）	less than or equal to	`599`

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

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
				}
		]
	}'

使用 Terraform 时，通过 ref 字段可在更新后保持稳定的规则 ID。添加该字段可防止 Terraform 在变更时重建规则。更多信息请参阅故障排除（Terraform 文档）。

此 PUT 请求对应于更新区域入口点规则集操作，用于替换 http_custom_errors 阶段入口点规则集中的任何现有规则。

带有更新状态代码的自定义 HTML 响应

本示例为 HTTP 状态代码为 500 的响应配置自定义 HTML 错误响应，并将响应状态代码重新定义为 503。

自定义错误规则配置：

Name（名称）：500 错误的自定义 HTML 响应
If incoming requests match（当传入请求匹配时）> Custom filter expression（自定义筛选表达式）：

字段运算符值

Response Status Code（响应状态代码） equals 500

如果使用表达式编辑器：
(http.response.code eq 500)
Response type（响应类型）：HTML response（HTML 响应）
Response code（响应代码）：503

字段	运算符	值
Response Status Code（响应状态代码）	equals	`500`

HTML response（HTML 响应）：

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

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

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": "<!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
				}
		]
	}'

此 PUT 请求对应于更新区域入口点规则集操作，用于替换 http_custom_errors 阶段入口点规则集中的任何现有规则。

Cloudflare 1020 错误的自定义 HTML 响应

本示例为 Cloudflare 错误 1020（访问被拒绝）配置自定义 HTML 错误响应。

自定义错误规则配置：

Name（名称）：1020 错误的自定义 HTML 响应
If incoming requests match（当传入请求匹配时）> Custom filter expression（自定义筛选表达式）

使用表达式编辑器：
(cf.response.1xxx_code eq 1020)
Response type（响应类型）：HTML response（HTML 响应）

HTML response（HTML 响应）：

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

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

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": "<!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
				}
		]
	}'

此 PUT 请求对应于更新区域入口点规则集操作，用于替换 http_custom_errors 阶段入口点规则集中的任何现有规则。

从 URL 创建的自定义错误资产

本示例配置了一个自定义错误规则，该规则为具有 500 HTTP 状态代码的响应返回名为 500_error_template 的先前创建的自定义错误资产。

自定义错误规则配置：

Name（名称）：HTTP 500 错误的提供资产
If incoming requests match（当传入请求匹配时）> Custom filter expression（自定义筛选表达式）：

字段运算符值

Response Status Code（响应状态代码） equals 500

如果使用表达式编辑器：
(http.response.code eq 500)
Response type（响应类型）：Custom error asset（自定义错误资产）
Asset（资产）：500_error_template

字段	运算符	值
Response Status Code（响应状态代码）	equals	`500`

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

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
				}
		]
	}'

此 PUT 请求对应于更新区域入口点规则集操作，用于替换 http_custom_errors 阶段入口点规则集中的任何现有规则。