--- title: Common API calls for Custom Errors description: Manage custom error rules and error pages using the Cloudflare API. image: https://developers.cloudflare.com/core-services-preview.png --- > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/rules/llms.txt > Use this file to discover all available pages before exploring further. [Skip to content](#%5Ftop) # Common API calls for Custom Errors 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: Terminal window ``` 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: Terminal window ``` 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`: Terminal window ``` 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} ``` ### Get a custom error asset The following `GET` request retrieves the details of an existing custom error asset at the zone level named `500_error_template`: Terminal window ``` 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 } ``` To retrieve 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 ``` ### Delete a custom error asset The following `DELETE` request deletes an existing custom error asset at the zone level named `500_error_template`: Terminal window ``` curl --request DELETE \ "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets/500_error_template" \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` If the request is successful, the response will have a `204` HTTP status code. To delete 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 ``` ### Get error page This example obtains the current configuration for the `Rate limiting block` error page (with ID `ratelimit_block`). Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Custom Pages Write` * `Custom Pages Read` * `Zone Settings Write` * `Zone Settings Read` Get a custom page ``` 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": [] } ``` The response indicates that the page is currently set to the Cloudflare default page (`"state": "default"`). For a list of error page identifiers, refer to [Error page types](https://developers.cloudflare.com/rules/custom-errors/reference/error-page-types/). ### Update error page This example defines a custom error page for `Rate limiting block` errors (with ID `ratelimit_block`) based on the provided URL. Required API token permissions At least one of the following [token permissions](https://developers.cloudflare.com/fundamentals/api/reference/permissions/)is required: * `Custom Pages Write` * `Zone Settings Write` Update a custom page ``` 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": [] } ``` To set the error page back to the default page, use `"state": "default"` in the request body. For a list of error page identifiers, refer to [Error page types](https://developers.cloudflare.com/rules/custom-errors/reference/error-page-types/). ## More resources * [Custom Error Pages API reference](https://developers.cloudflare.com/api/resources/custom%5Fpages/) ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/rules/","name":"Rules"}},{"@type":"ListItem","position":3,"item":{"@id":"/rules/custom-errors/","name":"Custom Errors"}},{"@type":"ListItem","position":4,"item":{"@id":"/rules/custom-errors/api-calls/","name":"Common API calls for Custom Errors"}}]} ```