diff --git a/public/__redirects b/public/__redirects index 34fbdfe5d69c305..69cf3b37040143e 100644 --- a/public/__redirects +++ b/public/__redirects @@ -1012,6 +1012,9 @@ /rules/page-rules/how-to/rewrite-host-headers/ /rules/origin-rules/examples/change-uri-path-and-host-header/ 301 /rules/page-rules/how-to/override-url-or-ip-address/ /rules/origin-rules/features/ 301 /rules/origin-rules/examples/change-uri-path-and-host-header/ /rules/origin-rules/tutorials/change-uri-path-and-host-header/ 301 +/rules/custom-errors/create-api/ /rules/custom-errors/create-rules/ 301 +/rules/custom-errors/error-tokens/ /rules/custom-errors/reference/error-tokens/ 301 +/rules/custom-errors/parameters/ /rules/custom-errors/reference/parameters/ 301 # ruleset engine /ruleset-engine/rules-language/fields/standard-fields/ /ruleset-engine/rules-language/fields/reference/ 301 @@ -1233,6 +1236,9 @@ /support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-10xxx-errors/ /support/troubleshooting/http-status-codes/cloudflare-10xxx-errors/ 301 /support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-1xxx-errors/ /support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/ 301 /support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/ /support/troubleshooting/http-status-codes/cloudflare-5xx-errors/ 301 +/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/ /rules/custom-errors/ 301 +/support/more-dashboard-apps/cloudflare-custom-pages/ /rules/custom-errors/ 301 +/support/more-dashboard-apps/ /support/ 301 # r2 /r2/platform/s3-compatibility/api/ /r2/api/s3/api/ 301 diff --git a/src/content/docs/rules/custom-errors/api-calls.mdx b/src/content/docs/rules/custom-errors/api-calls.mdx new file mode 100644 index 000000000000000..e80ef612472600c --- /dev/null +++ b/src/content/docs/rules/custom-errors/api-calls.mdx @@ -0,0 +1,169 @@ +--- +title: Common API calls +pcx_content_type: configuration +sidebar: + order: 5 +head: + - tag: title + content: Common API calls | Custom Error Assets +--- + +The following sections provide examples of common API calls for managing custom error assets 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: + +```bash +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" +}' +``` + +```json output +{ + "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: + +```txt +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: + +```bash +curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets" \ +--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" +``` + +```json output +{ + "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: + +```txt +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`: + +```bash +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" +}' +``` + +```json output +{ + "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: + +```txt +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`: + +```bash +curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets/500_error_template" \ +--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" +``` + +```json output +{ + "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: + +```txt +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`: + +```bash +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: + +```txt +https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/custom_pages/assets/$ASSET_NAME +``` diff --git a/src/content/docs/rules/custom-errors/create-api.mdx b/src/content/docs/rules/custom-errors/create-api.mdx deleted file mode 100644 index d35ac5bbe8e8476..000000000000000 --- a/src/content/docs/rules/custom-errors/create-api.mdx +++ /dev/null @@ -1,328 +0,0 @@ ---- -title: Create custom errors via API -pcx_content_type: how-to -sidebar: - order: 2 - label: Create via API -head: - - tag: title - content: Create custom errors via API ---- - -import { APIRequest } from "~/components"; - -To configure custom errors via API: - -1. (Optional) [Create a custom error asset](#create-a-custom-error-asset) based on a URL you provide. -2. [Create a custom error rule](#custom-error-rules) in the `http_custom_errors` phase, using the [Rulesets API](/ruleset-engine/rulesets-api/). - -## Custom error assets - -The following sections provide examples of common API calls for managing custom error assets 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 new a custom error asset in a zone based on the provided URL: - -```bash -curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets" \ ---header "Authorization: Bearer " \ ---header "Content-Type: application/json" \ ---data '{ - "name": "500_error_template", - "description": "Standard 5xx error template page", - "url": "https://example.com/errors/500_template.html" -}' -``` - -```json output -{ - "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: - -```txt -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: - -```bash -curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets" \ ---header "Authorization: Bearer " -``` - -```json output -{ - "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: - -```txt -https://api.cloudflare.com/client/v4/accounts/{account_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`: - -```bash -curl --request PUT \ -"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets/500_error_template" \ ---header "Authorization: Bearer " \ ---header "Content-Type: application/json" \ ---data '{ - "description": "Standard 5xx error template page", - "url": "https://example.com/errors/500_new_template.html" -}' -``` - -```json output -{ - "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: - -```txt -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`: - -```bash -curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets/500_error_template" \ ---header "Authorization: Bearer " -``` - -```json output -{ - "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: - -```txt -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`: - -```bash -curl --request DELETE \ -"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets/500_error_template" \ ---header "Authorization: Bearer " -``` - -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: - -```txt -https://api.cloudflare.com/client/v4/accounts/{account_id}/custom_pages/assets/{asset_name} -``` - -## Custom error rules - -When creating a custom error rule via API, make sure you: - -- Set the rule action to `serve_error`. -- Define the [rule parameters](/rules/custom-errors/parameters/#custom-error-rules) in the `action_parameters` field according to response type. -- Deploy the rule to the `http_custom_errors` phase. - -The first rule in the `http_custom_errors` phase ruleset that matches will be applied. No other rules in the ruleset will be matched or applied. Additionally, custom error rules defined at the zone level will have priority over rules defined at the account level. - ---- - -The provided examples use the following fields in their rule expressions: - -- [`http.response.code`](/ruleset-engine/rules-language/fields/reference/http.response.code/): Represents the HTTP status code returned to the client, either set by a Cloudflare product or returned by the origin server. Use this field to customize the response for error codes returned by the origin server or by a Cloudflare product such as a Worker. - -- [`cf.response.1xxx_code`](/ruleset-engine/rules-language/fields/reference/cf.response.1xxx_code/): Contains the specific error code for Cloudflare-generated errors. This field will only work for Cloudflare-generated errors such as [52X](/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/) and [1XXX](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/). - -### General procedure - -Follow this workflow to create a custom error rule for a given zone via API: - -1. Use the [List zone rulesets](/api/resources/rulesets/methods/list/) operation to check if there is already a ruleset for the `http_custom_errors` phase at the zone level. -2. If the phase ruleset does not exist, create it using the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, which allows you to create a ruleset if it does not exist and update all the rules in the ruleset. Create the ruleset in the `http_custom_errors` phase. - - If the phase ruleset already exists, use the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation to replace all the rules in the ruleset, or the [Add rule to ruleset](/ruleset-engine/rulesets-api/add-rule/) operation to add a rule to the existing rules in the ruleset. - -To create a custom error rule at the account level, use the corresponding account-level API endpoints. - -### Custom JSON response for all 5XX errors - -This example configures a custom JSON error response for all 5XX errors (`500`-`599`) in the zone with ID `$ZONE_ID`. The HTTP status code of the custom error response will be set to `530`. - - - -This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. - -### Custom HTML response with updated status code - -This example configures a custom HTML error response for responses with a `500` HTTP status code, and redefines the response status code to `503`. - -Application unavailable

Application temporarily unavailable

Please try again later.

', - content_type: "text/html", - status_code: 503, - }, - expression: "http.response.code eq 500", - enabled: true, - }, - ], - }} -/> - -This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. - -### Custom HTML response for Cloudflare 1020 errors - -This example configures a custom HTML error response for [Cloudflare error 1020](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/#error-1020-access-denied) (Access Denied). - -Access denied

You do not have access to this page

Contact us if you think this is an error.

', - content_type: "text/html", - }, - expression: "cf.response.1xxx_code eq 1020", - enabled: true, - }, - ], - }} -/> - -This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. - -### Custom error asset created from a URL - -This example configures a custom error rule returning a [previously created custom error asset](#create-a-custom-error-asset) named `500_error_template` for responses with a `500` HTTP status code. - - - -This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. - -## Required API token permissions - -The API token used in API requests to manage Custom Error Responses must have at least the following permission: - -- _Custom Error Rules_ > _Edit_ diff --git a/src/content/docs/rules/custom-errors/create-rules.mdx b/src/content/docs/rules/custom-errors/create-rules.mdx new file mode 100644 index 000000000000000..0b8e30a737bda3d --- /dev/null +++ b/src/content/docs/rules/custom-errors/create-rules.mdx @@ -0,0 +1,132 @@ +--- +title: Create custom error rules +pcx_content_type: how-to +sidebar: + order: 3 +--- + +import { APIRequest } from "~/components"; + +## In the dashboard + +### Create a custom error rule {/* create-a-custom-error-rule-dashboard */} + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and website. +2. Go to **Rules** > **Overview**. +3. Select **Create rule** > **Custom Error Rule**. +4. Enter a descriptive name for the rule in **Rule name**. +5. Under **If incoming requests match**, select one of the following options: + + - **Custom filter expression**: The rule will only apply to traffic matching a custom expression. Define the [rule expression](/ruleset-engine/rules-language/expressions/edit-expressions/) to configure which requests should be rewritten. Use either the Expression Builder or the Expression Editor to define the custom expression. For more information, refer to [Edit expressions in the dashboard](/ruleset-engine/rules-language/expressions/edit-expressions/). + + - **All incoming requests**: The rule will apply to all responses with a `400` status code or above, except for block and challenge actions issued by Cloudflare’s security products. + +6. In **Deliver a custom error response**, select the response type (either _Custom error asset_ or one of the available inline responses). + + If you select _Custom error asset_, select an existing custom error asset in **Asset**, or select **Create new asset** to [create a new custom error asset](#create-a-custom-error-asset-dashboard). + + If you select _JSON response_, _HTML response_, _Text response_, or _XML response_, enter the custom error response you want to send to web site visitors in **JSON response**, **HTML response**, **Text response**, or **XML response**, respectively. + The response can include [error tokens](/rules/custom-errors/reference/error-tokens/) that Cloudflare will replace with real values before sending the response to the visitor. The maximum response size is 10 KB. + +7. (Optional) In **Response code**, enter the HTTP status code of the response (an integer value between `400` and `999`). If provided, this value will override the current response status code. + +8. (Optional) Under **Place at**, define where to place the rule in the rules list: first rule in the list, last rule in the list, or in a custom position (after a given rule). + +9. To save and deploy your rule, select **Deploy**. If you are not ready to deploy your rule, select **Save as Draft**. + +### Create a custom error asset {/* create-a-custom-error-asset-dashboard */} + +1. In the **Create Custom Error Asset** sidebar, enter a name for the asset in **Asset name**. +2. (Optional) Enter a description for the asset in **Description**. +3. In **URL**, enter the URL of the page you want to fetch and store in Cloudflare's global network. Cloudflare will fetch all the page resources and store a minified version of the page you can use in one or more custom error rules. +4. Select **Save**. + +To review existing custom error assets, go to **Rules** > **Settings** > **Custom Error Assets** tab. + +## Via API + +To configure a custom error rule via API: + +1. (Optional) [Create a custom error asset](#create-a-custom-error-asset-api) based on a URL you provide. +2. [Create a custom error rule](#create-a-custom-error-rule-api) in the `http_custom_errors` phase, using the [Rulesets API](/ruleset-engine/rulesets-api/). + +### Create a custom error asset {/* create-a-custom-error-asset-api */} + +The following `POST` request creates new a custom error asset in a zone based on the provided URL: + +```bash +curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_pages/assets" \ +--header "Authorization: Bearer " \ +--json '{ + "name": "500_error_template", + "description": "Standard 5xx error template page", + "url": "https://example.com/errors/500_template.html" +}' +``` + +```json output +{ + "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 +} +``` + +### Create a custom error rule {/* create-a-custom-error-rule-api */} + +When creating a custom error rule via API, make sure you: + +- Set the rule action to `serve_error`. +- Define the [rule parameters](/rules/custom-errors/reference/parameters/#custom-error-rules) in the `action_parameters` field according to response type. +- Deploy the rule to the `http_custom_errors` phase. + +The first rule in the `http_custom_errors` phase ruleset that matches will be applied. No other rules in the ruleset will be matched or applied. Additionally, custom error rules defined at the zone level will have priority over rules defined at the account level. + +### General procedure + +Follow this workflow to create a custom error rule for a given zone via API: + +1. Use the [List zone rulesets](/api/resources/rulesets/methods/list/) operation to check if there is already a ruleset for the `http_custom_errors` phase at the zone level. +2. If the phase ruleset does not exist, create it using the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, which allows you to create a ruleset if it does not exist and update all the rules in the ruleset. Create the ruleset in the `http_custom_errors` phase. + + If the phase ruleset already exists, use the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation to replace all the rules in the ruleset, or the [Add rule to ruleset](/ruleset-engine/rulesets-api/add-rule/) operation to add a rule to the existing rules in the ruleset. + +To create a custom error rule at the account level, use the corresponding account-level API endpoints. + +### Example + +This example configures a custom error rule returning a [previously created custom error asset](#create-a-custom-error-asset-api) named `500_error_template` for responses with a `500` HTTP status code. + + + +This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. + +## Required API token permissions + +The API token used in API requests to manage Custom Error Rules and Custom Error Assets must have at least the following permission: + +- _Custom Error Rules_ > _Edit_ diff --git a/src/content/docs/rules/custom-errors/edit-error-pages.mdx b/src/content/docs/rules/custom-errors/edit-error-pages.mdx new file mode 100644 index 000000000000000..1037e80fa25df8e --- /dev/null +++ b/src/content/docs/rules/custom-errors/edit-error-pages.mdx @@ -0,0 +1,87 @@ +--- +title: Edit Error Pages +pcx_content_type: how-to +sidebar: + order: 2 +--- + +import { Details } from "~/components"; + +## Before you start + +Before defining a custom error page in your Cloudflare account, you will need to design and code that page. It can be hosted on your own web server or using a Cloudflare product like [Snippets](/rules/snippets/). + +When designing your custom error page, you can include page-specific [custom error tokens](/rules/custom-errors/reference/error-tokens/). Each custom error token provides diagnostic information that appears on the error page. + +To display a custom page for each error, create a separate page per error. For example, to create a custom error page for both **IP/Country Block** and **Interactive Challenge**, you must design and publish two separate pages. + +:::note[Notes] + +- Your custom error page should include a page-specific custom error token if applicable and cannot exceed 1.5 MB. Also, it must include HTML `` and `` tags. +- Make sure that the `referrer` meta tag is not present in your custom error page's HTML code since it will disrupt [Cloudflare challenges](/fundamentals/security/cloudflare-challenges/): `` + +::: + +You can use the following custom error template to start building your page: + +```html + + + + ::[REPLACE WITH CUSTOM ERROR TOKEN NAME]:: + + +``` + +
+ +The following HTML code is an example Custom Page for 5XX errors without styling: + +```html + + + + + 5XX Level Errors page + + +

5XX Level Errors

+

::CLOUDFLARE_ERROR_500S_BOX::

+ + +``` + +
+ +--- + +## Update an error page in the dashboard + +### Account-level custom error page + +To update an account-level custom error page: + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account. +2. Go to **Manage Account** > **Configurations**. +3. Select **Error Pages** and identify your desired custom error page type. +4. (Optional) To preview the current error page (default or custom), select the link in the **Show** column. +5. To edit the error page, select three dots > **Edit** next to the page type you previously identified. +6. To use Cloudflare's default page, select **Cloudflare default page.** To provide a custom error page, select **Custom page** and enter the URL of the custom error page you created. +7. Select **Confirm**. + +### Zone-level custom error page + +To edit a zone-level custom error page: + +1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and website. +2. Go to **Error Pages** and identify your desired custom error page type. +3. (Optional) To preview the current error page (default or custom), select the link in the **Show** column. +4. To edit the error page, select three dots > **Edit** next to the page type you previously identified. +5. To use Cloudflare's default page, select **Cloudflare default page.** To provide a custom error page, select **Custom page** and enter the URL of the custom error page you created. +6. Select **Confirm**. + +### Fetch custom error page again + +After successfully setting the content of the custom error page in **Error Pages**, you can remove the page from your origin server. + +If in the future, you need to update your custom error page, you must fetch the page again, even if the page URL remains unchanged. In this case, next to the page type you want to update, select the three dots > **Fetch custom page again**. diff --git a/src/content/docs/rules/custom-errors/error-tokens.mdx b/src/content/docs/rules/custom-errors/error-tokens.mdx deleted file mode 100644 index 6673d8b1e8f8116..000000000000000 --- a/src/content/docs/rules/custom-errors/error-tokens.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Error tokens -pcx_content_type: reference -sidebar: - order: 4 -head: - - tag: title - content: Custom error tokens ---- - -A custom error asset or inline response may include the following error tokens, which will be replaced with their real values before sending the response to the visitor: - -| Token | Description | -| --------------- | ------------------------------------------------------------------------ | -| `::CLIENT_IP::` | The visitor's IP address. | -| `::RAY_ID::` | A unique identifier given to every request that goes through Cloudflare. | -| `::GEO::` | The country or region associated with the visitor's IP address. | diff --git a/src/content/docs/rules/custom-errors/example-rules.mdx b/src/content/docs/rules/custom-errors/example-rules.mdx new file mode 100644 index 000000000000000..26b32f25f61e161 --- /dev/null +++ b/src/content/docs/rules/custom-errors/example-rules.mdx @@ -0,0 +1,221 @@ +--- +title: Example rules +pcx_content_type: configuration +sidebar: + order: 4 +--- + +import { Tabs, TabItem, APIRequest } from "~/components"; + +The provided examples use the following fields in their rule expressions: + +- [`http.response.code`](/ruleset-engine/rules-language/fields/reference/http.response.code/) (Response Status Code): Represents the HTTP status code returned to the client, either set by a Cloudflare product or returned by the origin server. Use this field to customize the response for error codes returned by the origin server or by a Cloudflare product such as a Worker. + +- [`cf.response.1xxx_code`](/ruleset-engine/rules-language/fields/reference/cf.response.1xxx_code/): Contains the specific error code for Cloudflare-generated errors. This field will only work for Cloudflare-generated errors such as [52X](/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/) and [1XXX](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/). + +### Custom JSON response for all 5XX errors + +This example configures a custom JSON error response for all 5XX errors (`500`-`599`) in a zone. The HTTP status code of the custom error response will be set to `530`. + + + +**Custom error rule configuration:** + +- **Name**: `Custom JSON response for all 5XX errors` + +- **If incoming requests match** > **Custom filter expression**: + + | Field | Operator | Value | Logic | + | -------------------- | ------------------------ | ----- | ----- | + | Response Status Code | greater than or equal to | `500` | And | + | Response Status Code | less than or equal to | `599` | | + + If using the Expression Editor:
+ `(http.response.code ge 500 and http.response.code le 599)` + +- **Response type**: _JSON response_ +- **Response code**: `530` +- **JSON response**: `{"message": "A server error occurred."}` + + + + + +This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. + + + +### Custom HTML response with updated status code + +This example configures a custom HTML error response for responses with a `500` HTTP status code, and redefines the response status code to `503`. + + + +**Custom error rule configuration:** + +- **Name**: `Custom HTML response for 500 errors` + +- **If incoming requests match** > **Custom filter expression**: + + | Field | Operator | Value | + | -------------------- | -------- | ----- | + | Response Status Code | equal to | `500` | + + If using the Expression Editor:
+ `(http.response.code eq 500)` + +- **Response type**: _HTML response_ +- **Response code**: `503` +- **HTML response**: + + ```txt + Application unavailable

Application temporarily unavailable

Please try again later.

+ ``` + + + +Application unavailable

Application temporarily unavailable

Please try again later.

', + content_type: "text/html", + status_code: 503, + }, + expression: "http.response.code eq 500", + enabled: true, + }, + ], + }} +/> + +This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. + + + +### Custom HTML response for Cloudflare 1020 errors + +This example configures a custom HTML error response for [Cloudflare error 1020](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/#error-1020-access-denied) (Access Denied). + + + +**Custom error rule configuration:** + +- **Name**: `Custom HTML response for 1020 errors` + +- **If incoming requests match** > **Custom filter expression** + + Use the Expression Editor:
+ `(cf.response.1xxx_code eq 1020)` + +- **Response type**: _HTML response_ +- **HTML response**: + + ```txt + Access denied

You do not have access to this page

Contact us if you think this is an error.

+ ``` + + + +Access denied

You do not have access to this page

Contact us if you think this is an error.

', + content_type: "text/html", + }, + expression: "cf.response.1xxx_code eq 1020", + enabled: true, + }, + ], + }} +/> + +This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. + + + +### Custom error asset created from a URL + +This example configures a custom error rule returning a previously created custom error asset named `500_error_template` for responses with a `500` HTTP status code. + + + +**Custom error rule configuration:** + +- **Name**: `Serve asset for HTTP 500 errors` + +- **If incoming requests match** > **Custom filter expression**: + + | Field | Operator | Value | + | -------------------- | -------- | ----- | + | Response Status Code | equal to | `500` | + + If using the Expression Editor:
+ `(http.response.code eq 500)` + +- **Response type**: _Custom error asset_ +- **Asset**: `500_error_template` + + + + + +This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset. + + diff --git a/src/content/docs/rules/custom-errors/index.mdx b/src/content/docs/rules/custom-errors/index.mdx index 6c524eefaf168c7..5ca211cc9f51a2d 100644 --- a/src/content/docs/rules/custom-errors/index.mdx +++ b/src/content/docs/rules/custom-errors/index.mdx @@ -3,40 +3,83 @@ pcx_content_type: concept title: Custom Errors sidebar: order: 10 - group: - badge: - text: Beta head: - tag: title - content: Custom Errors (beta) + content: Custom Errors --- import { FeatureTable, Render } from "~/components"; -Custom Errors (beta), powered by the [Ruleset Engine](/ruleset-engine/), allow you to define custom content for errors returned by an origin server or by a Cloudflare product (including Workers). Custom Errors will apply to responses whose HTTP status code is greater than or equal to `400` that match the expression of the custom error rule. +Use Custom Errors to return custom content to your website visitors in case of HTTP errors returned by an origin server or by a Cloudflare product (including Workers), or when showing a [security challenge](/fundamentals/security/cloudflare-challenges/). -To configure a custom error, create a custom error rule at the account or zone level. Zone-level rules take precedence over account-level rules. Custom error rules will override [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/) at the zone or account level. +You can configure custom error content using the following methods: -Custom Errors require that you [proxy the DNS records](/dns/proxy-status/) of your domain (or subdomain) through Cloudflare. +- [**Error Page**](#error-pages): An HTML page shown to website visitors when a specific error occurs (refer to the different error page types) or when showing a security challenge. Error Pages can be defined at the zone level and at the account level on paid plans, with zone-level configurations taking precedence. +- [**Custom Error Rule**](#custom-error-rules): Defines the conditions under which Cloudflare will serve a custom error response to visitors in case of HTTP errors (status codes `400` and above), and the exact content that will be served. A matching custom error rule has priority over an Error Page configured at the account or at the zone level that would apply to the same error. -:::note[Notes about the beta] -During the beta you can only create custom error rules [using the API](/rules/custom-errors/create-api/). -::: +Custom Errors require that you [proxy the DNS records](/dns/proxy-status/) of your domain (or subdomain) through Cloudflare. ## How it works -When defining the custom error to serve, you provide either the URL of an existing web page or an inline response. The URL can point to a webpage or to a different resource (such as JSON content). When you provide a URL, Cloudflare will gather any required images, CSS, and JavaScript code and save a minified version of the full page. This resource is called a [custom error asset](/rules/custom-errors/parameters/#custom-error-assets), which you can use in one or more custom error rules in same scope of the asset (zone or account). +Cloudflare has a set of default pages for presenting errors and challenges to your website visitors. You can customize those pages using Error Pages and Custom Error Rules. -When a custom error rule is triggered, Cloudflare will replace the body with the response you previously defined and (optionally) the response HTTP status code sent to the visitor. +When an error of a [specific type](/rules/custom-errors/reference/error-page-types/) occurs, Cloudflare does the following: -Cloudflare will keep any existing HTTP response headers except for `Content-Type` and `Content-Length`. +1. Search for a configured Error Page at the account level for the specific error. +2. Search for a configured Error Page at the zone level for the specific error (it will have priority over the account-level Error Page, if any). +3. Search for a matching custom error rule at the account level. The rule will have priority over 500 and 1000 class Error Pages at the account or zone level. +4. Search for a matching custom error rule at the zone level. The rule will have priority over 500 and 1000 class Error Pages at the account or zone level and over custom error rules at the account level. +5. If a security rule like a [WAF custom rule](/waf/custom-rules/) or a [rate limiting rule](/waf/rate-limiting-rules/) triggers a custom block response instead of a default Cloudflare WAF block page, the rule-specific block response will have priority over Error Pages or a matching custom error rule. +6. If any of the previous configurations apply, serve the custom error content to the visitor. If not, serve the default error page for the specific error type. -Additionally, you can configure [Response Header Transform Rules](/rules/transform/response-header-modification/) for error responses to add, change, or remove HTTP headers from the response. +:::note +To customize a challenge page or a block page, use an Error Page, since Custom Error Rules will not be applied to security actions originating from Cloudflare products. Keep in mind that [custom WAF response](/waf/custom-rules/create-dashboard/#configure-a-custom-response-for-blocked-requests) takes precedence over an Error Page and custom error rules. +::: ## Availability -Custom Errors are available in beta to all paid plans. The exact features depend on your Cloudflare plan: +Custom Errors are available to all paid plans. The exact features depend on your Cloudflare plan. + +--- + +## Error Pages + +Cloudflare uses a wide range of [error codes](/support/troubleshooting/http-status-codes/) to identify issues in handling request traffic. By default, these error pages mention Cloudflare; however, you can create custom error pages to provide a consistent brand experience for your users. + +Error Pages do not apply to responses with an HTTP status code of `500`, `501`, `503`, or `505`. These exceptions help avoid issues with specific API endpoints and other web applications. You can still customize responses for these status codes using Custom Error Rules. + +If you are on a Cloudflare paid plan, you can create custom error pages at the zone level or for your entire account. Zone-level error pages have priority over account-level error pages. + +Additionally, Enterprise customers can customize 5XX error pages (except errors `520`-`527`) at their origin via **Enable Origin Error Pages** in **Error Pages** in the dashboard. + +You can design custom error pages to appear during a security challenge or when an error occurs. For more information on the different error page types, refer to [Error page types](/rules/custom-errors/reference/error-page-types/). + +:::note +Cloudflare will return the default Cloudflare error page instead of your custom Error Pages if the incoming request does not contain an `accept-encoding` header. This does not apply to responses originating from Custom Error Rules. +::: + +## Custom Error Rules + +A custom error rule defines the conditions under which Cloudflare will serve custom error content to visitors in case of HTTP errors (status codes `400` and above), and the exact content that will be served to visitors. + +When defining the content to serve, you provide either an inline response or the URL of an existing webpage. The URL can point to a webpage or to a different resource such as JSON content. + +When you provide a URL, Cloudflare will gather any required images, CSS, and JavaScript code and save a minified version of the full page in the Cloudflare global network. This resource is called a [custom error asset](#custom-error-assets), which you can use in one or more custom error rules in the same scope of the asset (zone or account). + +When a custom error rule is triggered, Cloudflare will replace the body with the response you previously defined and (optionally) the response HTTP status code sent to the visitor. Cloudflare will keep any existing HTTP response headers except for `Content-Type` and `Content-Length`. + +Additionally, you can configure [Response Header Transform Rules](/rules/transform/response-header-modification/) for error responses to add, change, or remove HTTP headers from the response. + +Custom error rules have priority over [Error Pages](#error-pages). + +## Custom Error Assets + +A custom error asset corresponds to a web resource such as an HTML web page (including any referenced images, CSS, and JavaScript code) that Cloudflare fetches and saves based on a URL you provide, to be served to visitors as an error page. + +Once the custom error asset is stored in Cloudflare's global network, the URL you initially provided no longer needs to be available. You can update an existing custom error asset by fetching it again. The metadata associated with each custom error asset includes the timestamp when the last fetch occurred, and this information is displayed in the dashboard. + +You can use a custom error asset in one or more custom error rules in the same scope where you defined the asset (zone or account). diff --git a/src/content/docs/rules/custom-errors/parameters.mdx b/src/content/docs/rules/custom-errors/parameters.mdx deleted file mode 100644 index 6a000e02456a954..000000000000000 --- a/src/content/docs/rules/custom-errors/parameters.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Parameters -pcx_content_type: reference -sidebar: - order: 3 -head: - - tag: title - content: Custom errors parameters ---- - -import { Type, MetaInfo } from "~/components"; - -## Custom error rules - -Custom error rules define when a custom error gets triggered and the content that is served to visitors. - -Rule parameters are the following: - -- **`asset_name`** - - The name of the [custom error asset](#custom-error-assets) you previously uploaded. The asset may include [error tokens](/rules/custom-errors/error-tokens/) that will be replaced with real values before sending the error response to the visitor. - - A custom error rule can only reference an asset defined in the same scope as the rule (that is, in the same zone or account). - - You must provide either the `asset_name` or the `content` parameter. -- **`content`** - - The response body to return. It can include [error tokens](/rules/custom-errors/error-tokens/) that will be replaced with real values before sending the error response to the visitor. - - You must provide either the `asset_name` or the `content` parameter. - - The maximum content size is 10 KB. -- **`content_type`** - - The content type of the returned response. Must be one of the following: - - `text/html` - - `text/plain` - - `application/json` - - `text/xml` -- **`status_code`** - - The HTTP status code of the response. If provided, this value will override the current response status code. - - The status code must be between `400` and `999`. - -:::caution - -If you create an HTML error response, make sure the `referrer` meta tag is not present in the HTML code since it will disrupt [Cloudflare challenges](/fundamentals/security/cloudflare-challenges/): - -```html - -``` - -::: - -## Custom error assets - -A custom error asset corresponds to a web resource such as an HTML web page (including any referenced images, CSS, and JavaScript code) that Cloudflare fetches and saves based on a URL you provide, to be served to visitors as an error page. - -Custom error assets have the following parameters: - -- **`name`** - - The name of the custom error asset. - - Example value: `"500_error_template"`. - - An asset name can contain the following characters: - - Uppercase and lowercase letters (`A-Z` and `a-z`) - - Numbers (`0-9`) - - The underscore (`_`) character - - The maximum length is 200 characters. -- **`description`** - - A string describing the custom error asset. - - Example value: `"Standard 5xx error template page"`. -- **`url`** - - The URL of the page you want Cloudflare to fetch and store, to be served later to visitors as error pages according to the configured [custom error rules](#custom-error-rules). - - Example value: `"https://example.com/errors/500.html"`. - - When you create or update an asset and provide a URL, Cloudflare collects any images, CSS, and JavaScript code used in the page, minifies the content, and saves it internally. - - The content of the page at the specified URL may include [error tokens](/rules/custom-errors/error-tokens/) that will be replaced with real values before sending the error response to the visitor. - - If you update an asset and provide the same URL, Cloudflare will fetch the URL again, along with its resources, and store it internally. - - The maximum asset size is 1.5 MB. diff --git a/src/content/docs/rules/custom-errors/reference/error-page-types.mdx b/src/content/docs/rules/custom-errors/reference/error-page-types.mdx new file mode 100644 index 000000000000000..c03092f1c3bd3d5 --- /dev/null +++ b/src/content/docs/rules/custom-errors/reference/error-page-types.mdx @@ -0,0 +1,16 @@ +--- +title: Error page types +pcx_content_type: reference +sidebar: + order: 4 +--- + +| Page type | Description | +| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| WAF block | The page displayed when visitors are blocked by a [Web Application Firewall](/waf/) rule. This page returns a `403` status code. | +| IP/Country block | The page displayed when a request originates from an [blocked IP address or country](/waf/tools/ip-access-rules/). This page returns a `403` status code. | +| IP/Country challenge | Presents a challenge to visitors from specified IP addresses or countries. This page returns a `403` status code. For more information, refer to [IP Access rules](/waf/tools/ip-access-rules/). | +| 500 class errors | 500 class error pages are displayed when a web server is unable to process a request. For more information, refer to [Cloudflare 5XX errors](/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/). | +| 1000 class errors | 1000 class error pages are displayed when a domain’s configuration, security settings, or origin setup prevents Cloudflare from completing a request. For more information, refer to [Cloudflare 1XXX errors](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/). | +| Managed challenge / I'm Under Attack Mode | Presents different types of challenges to a visitor depending on the nature of their request and your security settings. This page returns a `403` status code. For more information, refer to [Under Attack mode](/fundamentals/reference/under-attack-mode/). | +| Rate limiting block | Displayed to visitors when they have been blocked by a [rate limiting rule](/waf/rate-limiting-rules/). This page returns a `429` status code. | diff --git a/src/content/docs/rules/custom-errors/reference/error-tokens.mdx b/src/content/docs/rules/custom-errors/reference/error-tokens.mdx new file mode 100644 index 000000000000000..36c5fe9d9e59d35 --- /dev/null +++ b/src/content/docs/rules/custom-errors/reference/error-tokens.mdx @@ -0,0 +1,36 @@ +--- +title: Error tokens +pcx_content_type: reference +sidebar: + order: 3 +head: + - tag: title + content: Custom error tokens +--- + +## For Error Pages + +Each custom error token provides diagnostic information or specific functionality that appears on the error page. Certain error pages require a page-specific custom error token. + +To display a custom page for each error, create a separate page per error. For example, to create a custom error page for both **IP/Country Block** and **Interactive Challenge**, you must design and publish two separate pages. + +The following custom error tokens are required by their respective custom error pages: + +| Token | Required for | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `::CAPTCHA_BOX::` | Interactive Challenge
Country Challenge (Managed Challenge)
Managed Challenge / I'm Under Attack Mode (Interstitial Page) | +| `::IM_UNDER_ATTACK_BOX::` | JS Challenge | +| `::CLOUDFLARE_ERROR_500S_BOX::` | 5XX Errors | +| `::CLOUDFLARE_ERROR_1000S_BOX::` | 1XXX Errors | + +Each custom error token has a default look and feel. However, you can use CSS to stylize each custom error tag using each tag's class ID. All the external resources like images, CSS, and scripts will be inlined during the process. As such, all external resources need to be available (that is, they must return `200 OK`) otherwise an error will be thrown. + +## For Custom Error Assets, inline responses, and Error Pages + +A custom error asset, inline response, or error page may also include the following error tokens, which will be replaced with their real values before sending the response to the visitor: + +| Token | Description | +| --------------- | ------------------------------------------------------------------------ | +| `::CLIENT_IP::` | The visitor's IP address. | +| `::RAY_ID::` | A unique identifier given to every request that goes through Cloudflare. | +| `::GEO::` | The country or region associated with the visitor's IP address. | diff --git a/src/content/docs/rules/custom-errors/reference/index.mdx b/src/content/docs/rules/custom-errors/reference/index.mdx new file mode 100644 index 000000000000000..b99be8fdbccaf01 --- /dev/null +++ b/src/content/docs/rules/custom-errors/reference/index.mdx @@ -0,0 +1,17 @@ +--- +title: Reference +pcx_content_type: navigation +sidebar: + order: 9 + group: + hideIndex: true +head: + - tag: title + content: Reference | Custom Errors +--- + +import { DirectoryListing } from "~/components"; + +This section contains reference information for Custom Errors. + + diff --git a/src/content/docs/rules/custom-errors/reference/parameters.mdx b/src/content/docs/rules/custom-errors/reference/parameters.mdx new file mode 100644 index 000000000000000..5c662375bb870db --- /dev/null +++ b/src/content/docs/rules/custom-errors/reference/parameters.mdx @@ -0,0 +1,112 @@ +--- +title: Parameters +pcx_content_type: reference +sidebar: + order: 2 +head: + - tag: title + content: Custom errors parameters +--- + +import { Type, MetaInfo } from "~/components"; + +## Custom error rules + +Custom error rules define when a custom error gets triggered and the content that is served to visitors. Rule parameters are the following: + +### Response type + +API name: _N/A_ (handled via [`asset_name`](#asset) and [`content_type`](#response) parameters) + +The content type of the inline response to send to the website visitor (JSON, HTML, Text, or XML), or **Custom error asset** if sending the content of a custom error asset. + +When using the API you must either set the `asset_name` or set both the `content_type` and `content` parameters. Refer to [JSON response / HTML response / Text response / XML response](#response). + +### Response code + +API name: **`status_code`** + +The HTTP status code of the response. If provided, this value will override the current response status code. + +The status code must be between `400` and `999`. + +### Asset + +API name: **`asset_name`** + +The name of the [custom error asset](#custom-error-assets) you previously uploaded (in the dashboard, you can create an asset when creating the rule). The asset may include [error tokens](/rules/custom-errors/reference/error-tokens/) that will be replaced with real values before sending the error response to the visitor. + +A custom error rule can only reference an asset defined in the same scope as the rule (that is, in the same zone or account). + +In the dashboard, this parameter is only available when you select `Custom error asset` in **Response type**. + +When using the API, you must provide either the `asset_name` or the `content` parameter. + +### JSON response / HTML response / Text response / XML response {/* response */} + +API names: **`content`** and **`content_type`** + +The response body to return. It can include [error tokens](/rules/custom-errors/reference/error-tokens/) that will be replaced with real values before sending the error response to the visitor. + +You must provide either the `asset_name` or the `content` parameter. + +The maximum content size is 10 KB. + +When using the API you must also set the `content_type` parameter, which defines the content type of the returned response. The value must be one of the following: + +- `text/html` +- `text/plain` +- `application/json` +- `text/xml` + +:::caution + +If you create an HTML error response, make sure the `referrer` meta tag is not present in the HTML code since it will disrupt [Cloudflare challenges](/fundamentals/security/cloudflare-challenges/): + +```html + +``` + +::: + +## Custom error assets + +A custom error asset corresponds to a web resource such as an HTML web page (including any referenced images, CSS, and JavaScript code) that Cloudflare fetches and saves based on a URL you provide, to be served to visitors as an error page. + +Custom error assets have the following parameters: + +### Asset name + +API name: **`name`** + +The name of the custom error asset. Example value: `"500_error_template"`. + +An asset name can contain the following characters: + + - Uppercase and lowercase letters (`A-Z` and `a-z`) + - Numbers (`0-9`) + - The underscore (`_`) character + +The maximum length is 200 characters. + +### Description + +API name: **`description`** + +A string describing the custom error asset. Example value: `"Standard 5xx error template page"`. + +### Asset address + +API name: **`url`** + +The URL of the page you want Cloudflare to fetch and store, to be served later to visitors as error pages according to the configured [custom error rules](#custom-error-rules). Example value: `"https://example.com/errors/500.html"`. + +When you create or update an asset and provide a URL, Cloudflare collects any images, CSS, and JavaScript code used in the page, minifies the content, and saves it internally. + +The content of the page at the specified URL may include [error tokens](/rules/custom-errors/reference/error-tokens/) that will be replaced with real values before sending the error response to the visitor. + +When using the dashboard, you can later trigger another fetch to get the latest version of the page along with its resources, and store it internally. + +When using the API, if you update an asset and provide the same URL, Cloudflare will fetch the URL again, along with its resources, and store it internally. + +The maximum asset size is 1.5 MB. diff --git a/src/content/docs/rules/custom-errors/troubleshooting.mdx b/src/content/docs/rules/custom-errors/troubleshooting.mdx new file mode 100644 index 000000000000000..fd0680aacb0ee04 --- /dev/null +++ b/src/content/docs/rules/custom-errors/troubleshooting.mdx @@ -0,0 +1,49 @@ +--- +title: Troubleshoot Error Pages issues +pcx_content_type: reference +sidebar: + order: 10 + label: Troubleshooting +--- + +## Cannot preview error page + +If Cloudflare cannot load your site or you have blocked the United States (US) via [IP Access rules](/waf/tools/ip-access-rules/) or WAF custom rules, publishing and previewing the error page will not work. + +A common error might look like the following: `Error fetching page: Fetch failed, https://example.com/ipcountryblock.html returned 403 (Code: 1202)`. + +Make sure that you are serving the custom error page with an `HTTP 200` status code, and that no WAF rule is blocking or challenging your custom error page. + +## Error pages for blocked requests + +If you block countries or IP addresses with an [IP Access rule](/waf/tools/ip-access-rules/), affected visitors will get a `1005` error and your **IP/Country Block** custom page. + +If you block countries or IP addresses with a [WAF custom rule](/waf/custom-rules/) and you do not configure a [custom response](/waf/custom-rules/create-dashboard/#configure-a-custom-response-for-blocked-requests) for blocked requests in the rule, affected visitors will get your **WAF Block** page. + +If you block requests due to a [rate limiting rule](/waf/rate-limiting-rules/) and you do not configure a [custom response for blocked requests](/waf/rate-limiting-rules/create-zone-dashboard/#configure-a-custom-response-for-blocked-requests) in the rule, affected visitors will get your **429 Errors** page displaying a Cloudflare `1015` error. + +If you block countries or IP addresses with a firewall rule (now deprecated), affected visitors will get your **1000 Class Errors** page. + +## 1XXX errors + +You cannot customize the following 1XXX errors via Error Pages: + +- `1001` - Unable to resolve +- `1003` - Bad Host header +- `1018` - Unable to resolve because of ownership lookup failure +- `1023` - Unable to resolve because of feature lookup failure + +## Custom error page size + +Your custom error page cannot be blank and cannot exceed 1.5 MB. To avoid exceeding the custom error page limit, preview your page before publishing to test your page size before publishing. + +## General troubleshooting advice + +If you encounter errors while attempting to preview or publish your custom error page, use an [HTML validator](https://validator.w3.org/) to ensure that your code resolves properly. + +Make sure that you are serving the custom error page with an `HTTP 200` status code. + +## More resources + +- [HTTP Status Codes](/support/troubleshooting/http-status-codes/) +- [Challenges](/fundamentals/security/cloudflare-challenges/) diff --git a/src/content/docs/rules/transform/response-header-modification/index.mdx b/src/content/docs/rules/transform/response-header-modification/index.mdx index 96eb41ef499b8c7..5727f9b50b7bae5 100644 --- a/src/content/docs/rules/transform/response-header-modification/index.mdx +++ b/src/content/docs/rules/transform/response-header-modification/index.mdx @@ -63,7 +63,7 @@ You can create a response header transform rule [in the dashboard](/rules/transf - Currently, there is a limited number of HTTP response headers that you cannot change. Cloudflare may remove restrictions for some of these HTTP response headers when presented with valid use cases. [Create a post in the community](https://community.cloudflare.com) for consideration. -- Any response header modifications will also apply to Cloudflare error pages and [custom error pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/). +- Any response header modifications will also apply to Cloudflare error pages and [custom error pages](/rules/custom-errors/). - Modifying `cache-control`, `CDN-Cache-Control`, or `Cloudflare-CDN-Cache-Control` headers will not change the way Cloudflare caches an object. Instead, you should create a [Cache Rule](/cache/how-to/cache-rules/). diff --git a/src/content/docs/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge.mdx b/src/content/docs/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge.mdx deleted file mode 100644 index 34bb803f7292d62..000000000000000 --- a/src/content/docs/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge.mdx +++ /dev/null @@ -1,193 +0,0 @@ ---- -pcx_content_type: troubleshooting -source: https://support.cloudflare.com/hc/en-us/articles/200172706-Configuring-Custom-Pages-Error-and-Challenge- -title: Configuring Custom Pages (Error and Challenge) ---- - -Cloudflare uses a wide range of [error codes](/support/troubleshooting/http-status-codes/) to identify issues in handling request traffic. By default, these error pages mention Cloudflare; however, custom error pages help you provide a consistent brand experience for your users. - -If you are on the Pro, Business, or Enterprise plan you can customize and brand these pages for your whole account or for specific domains. You can design custom error pages to appear during a security challenge or when an error occurs. - -:::note[Notes] - -- Responses with 500, 501, 503, and 505 HTTP status codes do not trigger custom error pages to avoid breaking specific API endpoints and other web applications. -- Your custom error pages are not used if requests do not contain `accept-encoding` headers. In these cases, Cloudflare will show the standard error pages to website visitors. - -::: - -Alternatively, Enterprise customers can customize 5XX error pages at their origin via **Enable Origin Error Pages** in the **Custom Pages** app in the dashboard. - -:::note -Enable Origin Error Pages excludes errors 520 to 527. -::: - ---- - -## Step 1: Create a custom page - -Before adding a custom error page to your Cloudflare account, you will need to design, code, and host that page on your own web server. - -You can use the following custom error template to start building your page: - -```html - - - - ::[REPLACE WITH CUSTOM ERROR TOKEN NAME]:: - - -``` - -:::caution[Warnings] - -- Your custom error page should include a page-specific custom error token if applicable and cannot exceed 1.43 MB. Also, it must include HTML `` and `` tags. -- Make sure that the `referrer` meta tag is not present in your custom error page's HTML code since it will disrupt [Cloudflare challenges](/fundamentals/security/cloudflare-challenges/): `` - -::: - -When published, any additional scripts, images, or stylesheets increase the size of your custom error page source by approximately 50%. - -### Custom Page example - -Here is sample code for a 5XX custom error page without styling: - -```html - - - - - 5XX Level Errors page - - -

5XX Level Errors

-

::CLOUDFLARE_ERROR_500S_BOX::

- - -``` - ---- - -## Step 2: Select your custom error tokens - -When designing your custom error page, you must include one page-specific custom error token.  Each custom error token provides diagnostic information that appears on the error page. - -To display a custom page for each error, create a separate page per error. For example, to create a custom error page for both **IP/Country Block** and **Interactive Challenge**, you must design and publish two separate pages. - -The following tables list each custom error token grouped by the applicable custom error page. - -| Token | Available to | -| --------------- | ------------ | -| `::CLIENT_IP::` | All pages | -| `::RAY_ID::` | All pages | - -:::caution -Only one page-specific custom error token can be used per page. -::: - -| Token | Available to | -| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `::GEO::` | IP/Country Block | -| `::CAPTCHA_BOX::` | Interactive Challenge
Country Challenge (Managed Challenge)
Managed Challenge / I'm Under Attack Mode (Interstitial Page) | -| `::IM_UNDER_ATTACK_BOX::` | JS Challenge | -| `::CLOUDFLARE_ERROR_500S_BOX::` | 5XX Errors | -| `::CLOUDFLARE_ERROR_1000S_BOX::` | 1XXX Errors | - ---- - -## Step 3: Style your custom page - -Each custom error token has a default look and feel. However, you can use CSS to stylize each custom error tag using each tag's class ID. If you are familiar with CSS styling, you can customize the look and feel of the error page using each tag's class ID. Please keep in mind that all the external resources like images, CSS, and scripts will be inlined during the process. As such, all external resources need to be available (that is, they must return 200 OK) otherwise an error will be thrown. - ---- - -## Step 4: Preview and Publish your custom page - -After customizing your custom error page, there are two options for adding the page to Cloudflare: - -- Account level: the custom error page will apply to every domain associated with your account. -- Domain level: the custom error page will apply to only one domain associated with your account. - -:::note - -If Cloudflare cannot load your site or you have blocked the United States (US) via [IP Access rules](/waf/tools/ip-access-rules/) or WAF custom rules, publishing and previewing the error page will not work. - -A common error might look like the following: `Error fetching page: Fetch failed, https://example.com/ipcountryblock.html returned 403 (Code: 1202)`. Make sure that you are serving the custom error page with an `HTTP 200` status code, and that no WAF rule is blocking or challenging your custom error page. - -::: - -:::note -When publishing the custom error page, the system will ignore query strings. This means that if the custom error page URL contains a query string the address published will remove `?` and anything after that (for example, `https://domain.com/5xx.html?removeimages` -> `https://domain.com/5xx.html`). -::: - -### Account-level custom error page - -To publish an account level custom error page: - -1. Log into your Cloudflare account. -2. Go to **Manage Account** > **Configurations**. -3. In the left navigation, click **Custom Pages**. -4. Identify your desired custom error page type, then click the **Custom Pages** button. A **Custom Page** dialog will appear. -5. Enter the URL of the custom error page you customized in your origin server, then click **Preview**. -6. Ensure all your styles and images are showing up as desired in the preview. -7. Once you are happy with the page preview, return to the **Custom Page** dialog, and click **Publish**. - -### Domain level custom error page - -To publish a domain level custom error page: - -1. Log into your Cloudflare account. -2. Choose the domain for which you would like to publish a custom error page. -3. Click the **Custom Pages** app. -4. Identify your desired custom error page type, then click the **Custom Pages** button. A **Custom Page** dialog will appear. -5. Enter the URL of the custom error page you customized in your origin server, then click **Preview**. -6. Ensure all your styles and images are showing up as desired in the preview. -7. Once you are happy with the page preview, return to the **Custom Page** dialog, and click **Publish**. - -### Update custom error page after publishing - -After successfully publishing the custom error page in the **Custom Pages** app, you can remove the page from your origin server. - -If in the future, you need to update your custom error page, you must re-publish the page at your origin and in the Cloudflare dashboard, even if the page URL remains unchanged. - ---- - -## Troubleshoot common custom pages issues - -### Error pages for blocked requests - -If you block countries or IP addresses with an [IP Access rule](/waf/tools/ip-access-rules/), affected visitors will get a `1005` error and your **IP/Country Block** custom page. - -If you block countries or IP addresses with a [WAF custom rule](/waf/custom-rules/) and you do not configure a [custom response](/waf/custom-rules/create-dashboard/#configure-a-custom-response-for-blocked-requests) for blocked requests in the rule, affected visitors will get your **WAF Block** page. - -If you block requests due to a [rate limiting rule](/waf/rate-limiting-rules/) and you do not configure a [custom response for blocked requests](/waf/rate-limiting-rules/create-zone-dashboard/#configure-a-custom-response-for-blocked-requests) in the rule, affected visitors will get your **429 Errors** page displaying a Cloudflare `1015` error. - -If you block countries or IP addresses with a firewall rule (now deprecated), affected visitors will get your **1000 Class Errors page**. - -### 1XXX errors - -**1XXX Errors** do not customize the following HTTP errors via the Custom Pages app: - -- 1001 - Unable to resolve -- 1003 - Bad Host header -- 1018 - Unable to resolve because of ownership lookup failure -- 1023 - Unable to resolve because of feature lookup failure - -### Custom error page size - -Your custom error page cannot be blank and cannot exceed 1.43 MB. To avoid exceeding the custom error page limit, preview your page before publishing to test your page size before publishing. - -### General troubleshooting advice - -- If you encounter errors while attempting to preview or publish your custom error page, use an [HTML validator](https://validator.w3.org/) to ensure that your code resolves properly. -- Make sure that you are serving the custom error page with an HTTP 200 status code. - ---- - -## Related resources - -- [WAF custom rules](/waf/custom-rules/) -- [Cloudflare challenges](/fundamentals/security/cloudflare-challenges/) -- [Troubleshooting Cloudflare errors](/support/troubleshooting/http-status-codes/) -- [IP Access rules](/waf/tools/ip-access-rules/) -- [Rate limiting rules](/waf/rate-limiting-rules/) -- [Firewall rules](/firewall/cf-firewall-rules/) (deprecated) diff --git a/src/content/docs/support/more-dashboard-apps/cloudflare-custom-pages/index.mdx b/src/content/docs/support/more-dashboard-apps/cloudflare-custom-pages/index.mdx deleted file mode 100644 index 226ad3c4dd9675f..000000000000000 --- a/src/content/docs/support/more-dashboard-apps/cloudflare-custom-pages/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -pcx_content_type: navigation -title: Cloudflare Custom Pages -sidebar: - order: 3 - ---- - -import { DirectoryListing } from "~/components" - -Below you will find links to the relevant sections for Cloudflare Custom Pages support-focused material. - - diff --git a/src/content/docs/support/more-dashboard-apps/index.mdx b/src/content/docs/support/more-dashboard-apps/index.mdx deleted file mode 100644 index 988d86bbfab8599..000000000000000 --- a/src/content/docs/support/more-dashboard-apps/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -pcx_content_type: navigation -title: More Dashboard Apps -sidebar: - order: 2 - ---- - -import { DirectoryListing } from "~/components" - -Below you will find links to the relevant sections for More Dashboard Apps support-focused material. - - diff --git a/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors.mdx b/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors.mdx index 742b75633c822d9..ff2fd81d81f19db 100644 --- a/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors.mdx +++ b/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors.mdx @@ -12,7 +12,7 @@ The errors covered in this document may occur when accessing a website proxied b HTTP errors such as `409`, `530`, `403`, and `429` are returned in the HTTP status header of a response, while 1XXX errors appear in the HTML body of the response. :::note[Custom Error Pages] -Cloudflare **[Custom Error Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/)** allows customers to customize the default error pages discussed in this article. +Cloudflare [Custom Errors](/rules/custom-errors/) allows customers to customize the default error pages discussed in this article. ::: ### Support and assistance diff --git a/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-5xx-errors.mdx b/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-5xx-errors.mdx index 790ca1e42290252..d7bbab92cc60dd0 100644 --- a/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-5xx-errors.mdx +++ b/src/content/docs/support/troubleshooting/http-status-codes/cloudflare-5xx-errors.mdx @@ -27,7 +27,7 @@ When contacting your hosting provider, share the following information: The cause of the error is not always found in the origin server's error logs. Be sure to check the logs of any load balancers, caches, proxies, or firewalls between Cloudflare and the origin web server. -Additional details to provide to your hosting provider or site administrator can be found in the error descriptions below. Note that Cloudflare [Custom Error Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/) can alter the appearance of default error pages discussed in this page. +Additional details to provide to your hosting provider or site administrator can be found in the error descriptions below. Note that Cloudflare [Custom Errors](/rules/custom-errors/) can alter the appearance of default error pages discussed in this page. ### Error analytics @@ -132,7 +132,7 @@ To resolve a `503` error, first determine whether the issue originates from your If the error does not contain `cloudflare` or `cloudflare-nginx` in the HTML response body, contact your hosting provider to verify if they rate limit requests to your origin web server. -#### 503 Error with `cloudflare` or `cloudflare-nginx` +#### 503 Error with `cloudflare` or `cloudflare-nginx` If the error contains `cloudflare` or `cloudflare-nginx` in the HTML response body, a connectivity issue occurred in a Cloudflare data center. Provide [Cloudflare support](/support/contacting-cloudflare-support/) with the following information: diff --git a/src/content/docs/waf/reference/legacy/old-rate-limiting/index.mdx b/src/content/docs/waf/reference/legacy/old-rate-limiting/index.mdx index 0f6f79ae1a4b1e6..7ef412330ee6834 100644 --- a/src/content/docs/waf/reference/legacy/old-rate-limiting/index.mdx +++ b/src/content/docs/waf/reference/legacy/old-rate-limiting/index.mdx @@ -134,7 +134,7 @@ For more information on challenge actions, refer to [Cloudflare challenges](/fun Setting a timeout shorter than the threshold causes the API to automatically increase the timeout to equal the threshold. -Visitors hitting a rate limit receive a default HTML page if a [custom error page](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/) is not specified. In addition, Business and Enterprise customers can specify a response in the rule itself. Refer to [Configure Advanced Response](#task-3-configure-advanced-response-only-business-and-enterprise-plans) for details. +Visitors hitting a rate limit receive a default HTML page if a [custom error page](/rules/custom-errors/) is not specified. In addition, Business and Enterprise customers can specify a response in the rule itself. Refer to [Configure Advanced Response](#task-3-configure-advanced-response-only-business-and-enterprise-plans) for details. --- diff --git a/src/content/docs/waf/reference/migration-guides/firewall-rules-to-custom-rules.mdx b/src/content/docs/waf/reference/migration-guides/firewall-rules-to-custom-rules.mdx index 6f3b2a23354f4fc..2e67c1b56a9528f 100644 --- a/src/content/docs/waf/reference/migration-guides/firewall-rules-to-custom-rules.mdx +++ b/src/content/docs/waf/reference/migration-guides/firewall-rules-to-custom-rules.mdx @@ -52,7 +52,7 @@ Requests blocked by a WAF custom rule will get a different response: the WAF blo If you have customized your 1xxx error page in Custom Pages for requests blocked by firewall rules, you will need to create a new response page for blocked requests using one of the above methods. -For more information on Custom Pages, refer to [Configuring Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/). +For more information on custom Error Pages, refer to [Custom Errors](/rules/custom-errors/). ### New Skip action replacing both Allow and Bypass actions diff --git a/src/content/partials/fundamentals/account-permissions-table.mdx b/src/content/partials/fundamentals/account-permissions-table.mdx index d260ebef39567ec..63b6d7c51c07d55 100644 --- a/src/content/partials/fundamentals/account-permissions-table.mdx +++ b/src/content/partials/fundamentals/account-permissions-table.mdx @@ -26,8 +26,8 @@ import { Markdown } from "~/components"; | Access: SSH Auditing Read | Grants read access to [Cloudflare Access SSH CAs](/cloudflare-one/connections/connect-networks/use-cases/ssh/ssh-infrastructure-access/). | | Access: SSH Auditing {props.editWord} | Grants write access to [Cloudflare Access SSH CAs](/cloudflare-one/connections/connect-networks/use-cases/ssh/ssh-infrastructure-access/). | | Account Analytics Read | Grants read access to [account analytics](/analytics/account-and-zone-analytics/account-analytics/). | -| Account Custom Pages Read | Grants read access to account-level [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/). | -| Account Custom Pages {props.editWord} | Grants write access to account-level [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/). | +| Account Custom Pages Read | Grants read access to account-level [Custom Error Pages](/rules/custom-errors/). | +| Account Custom Pages {props.editWord} | Grants write access to account-level [Custom Error Pages](/rules/custom-errors/). | | Account { props.src === "dash" ? "Filter" : "Rule" } Lists Read | Grants read access to Account Filter Lists. | | Account { props.src === "dash" ? "Filter" : "Rule" } Lists {props.editWord} | Grants write access to Account Filter Lists. | | Account Firewall Access Rules Read | Grants read access to account firewall access rules. | diff --git a/src/content/partials/fundamentals/zone-permissions-table.mdx b/src/content/partials/fundamentals/zone-permissions-table.mdx index 76a2e40403a3f92..8bb09657bae7481 100644 --- a/src/content/partials/fundamentals/zone-permissions-table.mdx +++ b/src/content/partials/fundamentals/zone-permissions-table.mdx @@ -28,8 +28,8 @@ import { Markdown } from "~/components"; | Config { props.src === "dash" ? "Rules" : "Settings" } {props.editWord} | Grants write access to [Configuration Rules](/rules/configuration-rules/). | | Custom { props.src === "dash" ? "Error Rules" : "Errors" } Read | Grants read access to [Custom Error Rules](/rules/custom-errors/). | | Custom { props.src === "dash" ? "Error Rules" : "Errors" } {props.editWord} | Grants write access to [Custom Error Rules](/rules/custom-errors/). | -| Custom Pages Read | Grants read access to [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/). | -| Custom Pages {props.editWord} | Grants write access to [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/). | +| Custom Pages Read | Grants read access to [Custom Error Pages](/rules/custom-errors/). | +| Custom Pages {props.editWord} | Grants write access to [Custom Error Pages](/rules/custom-errors/). | | { props.src === "dash" ? "Dmarc Management" : "Email Security DMARC Reports" } Read | Grants read access to [DMARC Management](/dmarc-management/). | | { props.src === "dash" ? "Dmarc Management" : "Email Security DMARC Reports" } {props.editWord} | Grants write access to [DMARC Management](/dmarc-management/). | | DNS Read | Grants read access to [DNS](/dns/). | diff --git a/src/content/plans/index.json b/src/content/plans/index.json index 2f7c9ff0b527314..8a14bb4a8e3d467 100644 --- a/src/content/plans/index.json +++ b/src/content/plans/index.json @@ -567,20 +567,6 @@ "global_configurations": { "title": "Global configurations", "link": "/fundamentals/global-configurations/", - "custom_pages": { - "title": "Custom error/challenge pages", - "link": "/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/", - "properties": { - "availability": { - "title": "Availability", - "summary": "Pro and above", - "free": "No", - "pro": "Yes", - "biz": "Yes", - "ent": "Yes" - } - } - }, "lists": { "title": "Lists", "link": "/waf/tools/lists/", @@ -1250,6 +1236,20 @@ "pro": 25, "biz": 50, "ent": 300 + }, + "x_custom_pages": { + "title": "Custom Error Pages", + "free": "No", + "pro": "Yes", + "biz": "Yes", + "ent": "Yes" + }, + "z_origin_error_pages": { + "title": "Enable Origin Error Pages", + "free": "No", + "pro": "No", + "biz": "No", + "ent": "Yes" } } },