Custom Error Rules の例

各例のルール式では、次のフィールドを使います。

http.response.code（Response Status Code）: クライアントへ返す HTTP ステータスコードです。Cloudflare 製品が設定したもの、またはオリジンサーバーが返したものです。オリジンサーバー、または Worker などの Cloudflare 製品が返すエラーコード向けにレスポンスをカスタマイズするときに使います。
cf.response.1xxx_code: Cloudflare が生成したエラーの具体的なエラーコードです。このフィールドは、52X や 1XXX など、Cloudflare が生成したエラーにだけ使えます。

すべての 5XX エラー向けのカスタム JSON レスポンス

この例は、ゾーン内のすべての 5XX エラー（500–599）に対して、カスタム JSON エラーレスポンスを設定します。カスタムエラーレスポンスの HTTP ステータスコードは 530 になります。

Custom Error Rule の設定:

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

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

Field	Operator	Value	Logic
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 を使う場合、更新をまたいでルール ID を安定させるには ref フィールドを使います。このフィールドを追加すると、変更時に Terraform がルールを再作成するのを防げます。詳細は Terraform ドキュメントのトラブルシューティングを参照してください。

この PUT リクエストは、ゾーンのエントリポイントルールセットを更新する操作に対応し、http_custom_errors フェーズのエントリポイントルールセット内の既存ルールをすべて置き換えます。

ステータスコードを差し替えるカスタム HTML レスポンス

この例は、HTTP ステータスコード 500 のレスポンス向けにカスタム HTML エラーレスポンスを設定し、レスポンスのステータスコードを 503 に差し替えます。

Custom Error Rule の設定:

Name: Custom HTML response for 500 errors
If incoming requests match > Custom filter expression:

Field Operator Value

Response Status Code equal to 500

Expression Editor を使う場合:
(http.response.code eq 500)
Response type: HTML response
Response code: 503

Field	Operator	Value
Response Status Code	equal to	`500`

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>

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

Cloudflare 1020 エラー向けのカスタム HTML レスポンス

この例は、Cloudflare エラー 1020（Access Denied）向けに、カスタム HTML エラーレスポンスを設定します。

Custom Error Rule の設定:

Name: Custom HTML response for 1020 errors
If incoming requests match > Custom filter expression

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>

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

URL から作成した custom error asset

この例は、HTTP ステータスコード 500 のレスポンス向けに、あらかじめ作成した 500_error_template という custom error asset を返す Custom Error Rule を設定します。

Custom Error Rule の設定:

Name: Serve asset for HTTP 500 errors
If incoming requests match > Custom filter expression:

Field Operator Value

Response Status Code equal to 500

Expression Editor を使う場合:
(http.response.code eq 500)
Response type: Custom error asset
Asset: 500_error_template

Field	Operator	Value
Response Status Code	equal to	`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
				}
		]
	}'