← Cloudflare Rules / rules / custom-errors

Běžná volání API pro Custom Errors

Následující části obsahují příklady běžných volání API pro správu vlastních chybových assetů a Error Pages na úrovni zóny.

Chcete-li provést stejné operace na úrovni účtu, použijte odpovídající API endpointy na úrovni účtu.

Vytvořte vlastní chybový soubor

Následující POST požadavek vytvoří nový vlastní chybový prostředek v zóně na základě zadané 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
}

Chcete-li vytvořit asset na úrovni účtu, použijte endpoint na úrovni účtu:

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

Seznam vlastních chybových assetů

Následující GET požadavek načte seznam vlastních chybových prostředků nakonfigurovaných v zóně:

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

Chcete-li získat seznam assetů na úrovni účtu, použijte endpoint na úrovni účtu:

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

Aktualizace vlastního chybového assetu

Následující PUT požadavek aktualizuje URL existujícího vlastního chybového prostředku na úrovni zóny s názvem 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
}

Popis a URL adresu assetu můžete aktualizovat. Název assetu po vytvoření změnit nelze.

Pokud při aktualizaci assetu zadáte stejnou URL, Cloudflare tuto URL znovu načte i se všemi souvisejícími zdroji.

Chcete-li aktualizovat asset na úrovni účtu, použijte endpoint na úrovni účtu:

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

Získat Custom Error Asset

Následující GET požadavek načte podrobnosti existujícího vlastního chybového prostředku na úrovni zóny s názvem 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
}

Chcete-li získat asset na úrovni účtu, použijte endpoint na úrovni účtu:

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

Odstranění vlastního chybového aktiva

Následující DELETE požadavek odstraní existující vlastní chybový prostředek na úrovni zóny s názvem 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"

Pokud je požadavek úspěšný, odpověď bude mít 204 stavový kód HTTP.

Chcete-li odstranit asset na úrovni účtu, použijte endpoint na úrovni účtu:

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

Získat chybovou stránku

Tento příklad získává aktuální konfiguraci pro Rate limiting block chybové stránce (s ID ratelimit_block).

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

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

Získat vlastní stránku

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

Odpověď znamená, že stránka je aktuálně nastavena na výchozí stránku Cloudflare ("state": "default").

Seznam identifikátorů chybových stránek naleznete v Typy chybových stránek.

Aktualizace chybové stránky

Tento příklad definuje vlastní chybovou stránku pro Rate limiting block chybách (s ID ratelimit_block) na základě zadané URL adresy.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:

Custom Pages Write
Zone Settings Write

Aktualizace vlastní stránky

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

Chcete-li vrátit chybovou stránku zpět na výchozí, použijte "state": "default" v těle požadavku.

Seznam identifikátorů chybových stránek naleznete v Typy chybových stránek.

Další zdroje

Referenční dokumentace API pro vlastní chybové stránky