← Правила Cloudflare / rules / custom-errors

Частые вызовы API для Custom Errors

В следующих разделах приведены примеры типичных вызовов API для управления пользовательскими ресурсами ошибок и Error Pages на уровне зоны.

Чтобы выполнить те же операции на уровне аккаунта, используйте соответствующие конечные точки API уровня аккаунта.

Создайте custom error asset

Следующие POST запрос создаёт новый ресурс пользовательской ошибки в зоне на основе указанного URL:

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

Список пользовательских ресурсов ошибок

Следующие GET запрос возвращает список ресурсов пользовательских ошибок, настроенных в зоне:

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

Обновление пользовательского ресурса ошибки

Следующие PUT запрос обновляет URL существующего ресурса пользовательской ошибки на уровне зоны с именем 500_error_template:

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}

Получение настраиваемого ресурса ошибки

Следующие GET запрос возвращает сведения о существующем ресурсе пользовательской ошибки на уровне зоны с именем 500_error_template:

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

Удаление пользовательского ресурса ошибки

Следующие DELETE запрос удаляет существующий ресурс пользовательской ошибки на уровне зоны с именем 500_error_template:

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).

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

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

Получение настраиваемой страницы

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

Список идентификаторов страниц ошибок см. в Типы страниц ошибок.

Обновление страницы ошибки

В этом примере задается пользовательская страница ошибки для Rate limiting block ошибки (с ID ratelimit_block) на основе указанного URL-адреса.

Необходимые разрешения API-токена

Хотя бы одно из следующих права доступа токена требуется:

Custom Pages Write
Zone Settings Write

Обновление пользовательской страницы

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_IDENTIFIER/custom_pages/ratelimit_block" \
	--request PUT \
	--header "X-Auth-Email: $CLOUDFLARE_EMAIL" \
	--header "X-Auth-Key: $CLOUDFLARE_API_KEY" \
	--json '{
		"state": "customized",
		"url": "https://example.com/rate_limiting_block_error_page.html"
	}'

{
	"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:35:32.639114Z",
		"url": "https://example.com/rate_limiting_block_error_page.html",
		"state": "customized"
	},
	"success": true,
	"errors": [],
	"messages": []
}

Чтобы вернуть страницу ошибки к стандартной, используйте "state": "default" в теле запроса.

Список идентификаторов страниц ошибок см. в Типы страниц ошибок.

Дополнительные ресурсы

Справочник по API Custom Error Pages