Skip to content

Common API calls for Custom Errors

Last updated View as MarkdownAgent setup

The following sections provide examples of common API calls for managing custom error assets and Error Pages at the zone level.

To perform the same operations at the account level, use the corresponding account-level API endpoints.

Create a custom error asset

The following POST request creates a new custom error asset in a zone based on the provided 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
}

To create an asset at the account level, use the account-level endpoint:

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

List custom error assets

The following GET request retrieves a list of custom error assets configured in the zone:

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

To retrieve a list of assets at the account level, use the account-level endpoint:

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

Update a custom error asset

The following PUT request updates the URL of an existing custom error asset at the zone level named 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
}

You can update the asset description and URL. You cannot update the asset name after creation.

If you provide the same URL when updating an asset, Cloudflare will fetch the URL again, along with its resources.

To update an asset at the account level, use the account-level endpoint:

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