Custom Errors 的常用 API 调用

使用 Cloudflare API 管理 custom error 规则和错误页面。以下各节提供了在 zone 级别管理 custom error 资源和 Error Pages 的常用 API 调用示例。

要在账户级别执行相同操作，请使用对应的账户级 API 端点。

创建 custom error 资源

以下 POST 请求根据提供的 URL 在 zone 中创建新的 custom error 资源：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
  "name": "500_error_template",
  "description": "Standard 5xx error template page",
  "url": "https://example.com/errors/500_template.html"
}'

{
	"result": {
		"name": "500_error_template",
		"description": "Standard 5xx error template page",
		"url": "https://example.com/errors/500_template.html",
		"last_updated": "2025-02-10T11:36:07.810215Z",
		"size_bytes": 2048
	},
	"success": true
}

要在账户级别创建资源，请使用账户级端点：

https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/custom_pages/assets

列出 custom error 资源

以下 GET 请求检索 zone 中已配置的 custom error 资源列表：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
	"result": [
		{
			"name": "500_error_template",
			"description": "Standard 5xx error template page",
			"url": "https://example.com/errors/500_template.html",
			"last_updated": "2025-02-10T11:36:07.810215Z",
			"size_bytes": 2048
		}
		// ...
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"count": 2,
		"page": 1,
		"per_page": 20,
		"total_count": 2,
		"total_pages": 1
	}
}

要检索账户级别的资源列表，请使用账户级端点：

https://api.cloudflare.com/client/v4/accounts/$ZONE_ID/custom_pages/assets

更新 custom error 资源

以下 PUT 请求更新 zone 级别名为 500_error_template 的现有 custom error 资源的 URL：

curl --request PUT \
"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets/500_error_template" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
  "description": "Standard 5xx error template page",
  "url": "https://example.com/errors/500_new_template.html"
}'

{
	"result": {
		"name": "500_error_template",
		"description": "Standard 5xx error template page",
		"url": "https://example.com/errors/500_new_template.html",
		"last_updated": "2025-02-10T13:13:07.810215Z",
		"size_bytes": 3145
	},
	"success": true
}

你可以更新资源描述和 URL。创建后无法更新资源名称。

如果更新资源时提供相同的 URL，Cloudflare 将再次获取该 URL 及其资源。

要在账户级别更新资源，请使用账户级端点：

https://api.cloudflare.com/client/v4/accounts/{account_id}/custom_pages/assets/{asset_name}

获取 custom error 资源

以下 GET 请求检索 zone 级别名为 500_error_template 的现有 custom error 资源详情：

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets/500_error_template" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
	"result": {
		"name": "500_error_template",
		"description": "Standard 5xx error template page",
		"url": "https://example.com/errors/500_new_template.html",
		"last_updated": "2025-02-10T13:13:07.810215Z",
		"size_bytes": 3145
	},
	"success": true
}

要检索账户级别的资源，请使用账户级端点：

https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/custom_pages/assets/$ASSET_NAME

删除 custom error 资源

以下 DELETE 请求删除 zone 级别名为 500_error_template 的现有 custom error 资源：

curl --request DELETE \
"https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets/500_error_template" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

如果请求成功，响应将具有 204 HTTP 状态码。

要在账户级别删除资源，请使用账户级端点：

https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/custom_pages/assets/$ASSET_NAME

获取错误页面

此示例获取 Rate limiting block 错误页面（ID 为 ratelimit_block）的当前配置。

Required API token permissions

At least one of the following token permissions is required:

Custom Pages Write
Custom Pages Read
Zone Settings Write
Zone Settings Read

Get a custom pagebash

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_IDENTIFIER/custom_pages/ratelimit_block" \
	--request GET \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY"

{
	"result": {
		"id": "ratelimit_block",
		"description": "Rate limit Block",
		"required_tokens": [],
		"preview_target": "block:rate-limit",
		"created_on": "2025-06-03T08:33:17.091587Z",
		"modified_on": "2025-06-03T08:33:17.091587Z",
		"url": null,
		"state": "default"
	},
	"success": true,
	"errors": [],
	"messages": []
}

响应表明该页面当前设置为 Cloudflare 默认页面（"state": "default"）。

有关错误页面标识符列表，请参阅 Error page types。

更新错误页面

此示例根据提供的 URL 为 Rate limiting block 错误（ID 为 ratelimit_block）定义自定义错误页面。