From 06b6e82f2c3700a352bd26ca219b5acd8b2c6252 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Mon, 10 Feb 2025 11:56:46 +0000 Subject: [PATCH 1/8] [Rules] Rename section name to Custom Errors (w/ redirects) --- public/_redirects | 36 +++++++------- .../rules/custom-error-responses/index.mdx | 41 ---------------- .../create-api.mdx | 2 +- .../error-tokens.mdx | 4 +- .../docs/rules/custom-errors/index.mdx | 48 +++++++++++++++++++ .../parameters.mdx | 6 +-- src/content/docs/rules/index.mdx | 10 ++-- .../docs/rules/reference/esc-deprecation.mdx | 37 ++++++-------- .../ruleset-engine/reference/phases-list.mdx | 2 +- src/content/fields/index.yaml | 4 +- .../fundamentals/zone-permissions-table.mdx | 10 ++-- 11 files changed, 100 insertions(+), 100 deletions(-) delete mode 100644 src/content/docs/rules/custom-error-responses/index.mdx rename src/content/docs/rules/{custom-error-responses => custom-errors}/create-api.mdx (97%) rename src/content/docs/rules/{custom-error-responses => custom-errors}/error-tokens.mdx (75%) create mode 100644 src/content/docs/rules/custom-errors/index.mdx rename src/content/docs/rules/{custom-error-responses => custom-errors}/parameters.mdx (79%) diff --git a/public/_redirects b/public/_redirects index 03303d77375baec..96c9a07ffcc4c04 100644 --- a/public/_redirects +++ b/public/_redirects @@ -1833,20 +1833,13 @@ /http-applications/* /version-management/:splat 301 /http3/* https://www.cloudflare.com/learning/performance/what-is-http3/ 301 /railgun/* / 301 -/rules/bulk-redirects/* /rules/url-forwarding/bulk-redirects/:splat 301 -/rules/url-forwarding/dynamic-redirects/* /rules/url-forwarding/single-redirects/:splat 301 /ssl/ssl-tls/* /ssl/reference/:splat 301 /ssl/reference/cipher-suites/* /ssl/edge-certificates/additional-options/cipher-suites/:splat 301 /ssl/reference/migration-guides/digicert-update/* /ssl/reference/migration-guides/ 301 /support/account-management-billing/billing-cloudflare-add-on-services/* https://www.cloudflare.com/plans/ 301 /tenant/tutorial/* /tenant/get-started/ 301 -/waf/managed-rulesets/* /waf/managed-rules/:splat 301 -/firewall/recipes/* /waf/custom-rules/use-cases/:splat 301 /workers/wrangler-legacy/* /workers/wrangler/migration/v1-to-v2/wrangler-legacy/:splat 301 -/waf/custom-rulesets/* /waf/account/custom-rulesets/:splat 301 -/waf/custom-rules/custom-rulesets/* /waf/account/custom-rulesets/:splat 301 -/waf/exposed-credentials-check/* /waf/managed-rules/check-for-exposed-credentials/:splat 301 -/waf/security-events/* /waf/analytics/security-events/:splat 301 +/firewall/recipes/* /waf/custom-rules/use-cases/:splat 301 /web3/polygon-gateway/* /web3/ 301 /vectorize/configuration/* /vectorize/best-practices/:splat 301 @@ -1895,15 +1888,6 @@ ## Secure your Internet Traffic /learning-paths/secure-internet-traffic/connect-devices/* /learning-paths/secure-internet-traffic/connect-devices-networks/:splat 301 - -# Old WAF changelog entries -/waf/change-log/2019-* /waf/change-log/historical-2019/ 301 -/waf/change-log/2020-* /waf/change-log/historical-2020/ 301 -/waf/change-log/2021-* /waf/change-log/historical-2021/ 301 -/waf/change-log/2022-* /waf/change-log/historical-2022/ 301 -/waf/change-log/2023-* /waf/change-log/historical-2023/ 301 -/waf/change-log/2024-* /waf/change-log/historical-2024/ 301 - # Cloudflare for SaaS /ssl/ssl-for-saas/common-tasks/* /cloudflare-for-platforms/cloudflare-for-saas/ 301 /ssl/ssl-for-saas/reference/* /cloudflare-for-platforms/cloudflare-for-saas/reference/ 301 @@ -1919,6 +1903,24 @@ /magic-wan/connector/* /magic-wan/configuration/connector/:splat 301 /magic-wan/configuration/connector/dhcp/* /magic-wan/configuration/connector/network-options/dhcp/:splat 301 +# Rules +/rules/bulk-redirects/* /rules/url-forwarding/bulk-redirects/:splat 301 +/rules/url-forwarding/dynamic-redirects/* /rules/url-forwarding/single-redirects/:splat 301 +/rules/custom-error-responses/* /rules/custom-errors/:splat 301 + +# WAF +/waf/managed-rulesets/* /waf/managed-rules/:splat 301 +/waf/custom-rulesets/* /waf/account/custom-rulesets/:splat 301 +/waf/custom-rules/custom-rulesets/* /waf/account/custom-rulesets/:splat 301 +/waf/exposed-credentials-check/* /waf/managed-rules/check-for-exposed-credentials/:splat 301 +/waf/security-events/* /waf/analytics/security-events/:splat 301 +/waf/change-log/2019-* /waf/change-log/historical-2019/ 301 +/waf/change-log/2020-* /waf/change-log/historical-2020/ 301 +/waf/change-log/2021-* /waf/change-log/historical-2021/ 301 +/waf/change-log/2022-* /waf/change-log/historical-2022/ 301 +/waf/change-log/2023-* /waf/change-log/historical-2023/ 301 +/waf/change-log/2024-* /waf/change-log/historical-2024/ 301 + # Workers /workers/reference/apis/* /workers/runtime-apis/:splat 301 /workers/templates/pages/* /workers/examples/:splat 301 diff --git a/src/content/docs/rules/custom-error-responses/index.mdx b/src/content/docs/rules/custom-error-responses/index.mdx deleted file mode 100644 index f60a1be170dc1dc..000000000000000 --- a/src/content/docs/rules/custom-error-responses/index.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -pcx_content_type: concept -title: Custom Error Responses -sidebar: - order: 12 - group: - badge: - text: Beta -head: - - tag: title - content: Custom Error Responses (beta) ---- - -Custom Error Responses (beta), powered by the [Ruleset Engine](/ruleset-engine/), allow you to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). Custom Error Responses will apply to responses whose HTTP status code is greater than or equal to 400 that match the expression of the custom error response rule. - -To configure a custom error response, create a custom error response rule at the zone level. Custom error response rules will override [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/) at the zone or account level. - -Custom Error Responses require that you [proxy the DNS records](/dns/manage-dns-records/reference/proxied-dns-records/) of your domain (or subdomain) through Cloudflare. - -:::note[Notes about the beta] - -During the beta, you can define Custom Error Responses using inline templates and specify the response's content type and HTTP status code. - -Additionally, at this stage you can only create custom error response rules [using the API](/rules/custom-error-responses/create-api/). - -::: - -## How it works - -When a custom error response is triggered, Cloudflare will replace the body and (optionally) the HTTP status code of the response sent to the visitor. Cloudflare will keep any existing HTTP response headers except for `Content-Type` and `Content-Length`. - -Additionally, you can configure [HTTP response header modification rules](/rules/transform/response-header-modification/) for error responses to add, change, or remove HTTP headers from the error response. - -## Availability - -Custom Error Responses are available in beta to all paid plans. The exact features depend on your Cloudflare plan: - -| | Free | Pro | Business | Enterprise | -| ------------------------------------- | :--: | :-: | :------: | :--------: | -| Custom Error Responses | No | Yes | Yes | Yes | -| Number of custom error response rules | — | 5 | 20 | 50 | diff --git a/src/content/docs/rules/custom-error-responses/create-api.mdx b/src/content/docs/rules/custom-errors/create-api.mdx similarity index 97% rename from src/content/docs/rules/custom-error-responses/create-api.mdx rename to src/content/docs/rules/custom-errors/create-api.mdx index 460cb04715190e0..01cf5974e7f40b5 100644 --- a/src/content/docs/rules/custom-error-responses/create-api.mdx +++ b/src/content/docs/rules/custom-errors/create-api.mdx @@ -15,7 +15,7 @@ Configure Custom Error Responses as [rules](/ruleset-engine/about/rules/) belong When creating a custom error response via API, make sure you: - Set the rule action to `serve_error`. -- Define the [parameters](/rules/custom-error-responses/parameters/) in the `action_parameters` field according to response type. +- Define the [parameters](/rules/custom-errors/parameters/) in the `action_parameters` field according to response type. - Deploy the custom error response rule to the `http_custom_errors` phase at the zone level. 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. diff --git a/src/content/docs/rules/custom-error-responses/error-tokens.mdx b/src/content/docs/rules/custom-errors/error-tokens.mdx similarity index 75% rename from src/content/docs/rules/custom-error-responses/error-tokens.mdx rename to src/content/docs/rules/custom-errors/error-tokens.mdx index 13a96751434a482..b29959b69b37c3b 100644 --- a/src/content/docs/rules/custom-error-responses/error-tokens.mdx +++ b/src/content/docs/rules/custom-errors/error-tokens.mdx @@ -5,11 +5,11 @@ sidebar: order: 4 head: - tag: title - content: Custom error response tokens + content: Custom error tokens --- -A custom response may include the following error tokens, which will be replaced with their real values before sending the response to the visitor: +A custom error may include the following error tokens, which will be replaced with their real values before sending the response to the visitor: diff --git a/src/content/docs/rules/custom-errors/index.mdx b/src/content/docs/rules/custom-errors/index.mdx new file mode 100644 index 000000000000000..04cb44a398181f0 --- /dev/null +++ b/src/content/docs/rules/custom-errors/index.mdx @@ -0,0 +1,48 @@ +--- +pcx_content_type: concept +title: Custom Errors +sidebar: + order: 12 + group: + badge: + text: Beta +head: + - tag: title + content: Custom Errors (beta) +--- + +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. + +To configure a custom error, create a custom error rule at the account or zone level. 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. + +Custom Errors require that you [proxy the DNS records](/dns/manage-dns-records/reference/proxied-dns-records/) of your domain (or subdomain) through Cloudflare. + +:::note[Notes about the beta] + +During the beta, you can define a custom error using a URL or an inline template, and specify the response's content type and HTTP status code. + +Additionally, at this stage you can only create custom error rules [using the API](/rules/custom-errors/create-api/). + +::: + +## How it works + +When defining the custom error to serve, you provide either the URL of an existing HTML page or inline HTML content. When you provide a URL, Cloudflare will gather the required images, CSS, and JavaScript code and save a minified version of the full page. This full page is called a custom error asset, which you can use in one or more custom error rules in same scope of the asset (zone or account). + +When a custom error 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 [HTTP response header modification rules](/rules/transform/response-header-modification/) for error responses to add, change, or remove HTTP headers from the response. + +## Availability + +Custom Errors are available in beta to all paid plans. The exact features depend on your Cloudflare plan: + +| | Free | Pro | Business | Enterprise | +| ----------------------------- | :--: | :-: | :------: | :--------: | +| Custom Errors | No | Yes | Yes | Yes | +| Number of custom error rules | — | 5 | 20 | 50 | +| Number of custom error assets | — | 5 | 20 | 50 | + +The size limit of each custom error asset is 1.5 MB. diff --git a/src/content/docs/rules/custom-error-responses/parameters.mdx b/src/content/docs/rules/custom-errors/parameters.mdx similarity index 79% rename from src/content/docs/rules/custom-error-responses/parameters.mdx rename to src/content/docs/rules/custom-errors/parameters.mdx index 90e5dc53156fd4f..c7f61fbcf6ec926 100644 --- a/src/content/docs/rules/custom-error-responses/parameters.mdx +++ b/src/content/docs/rules/custom-errors/parameters.mdx @@ -5,14 +5,14 @@ sidebar: order: 3 head: - tag: title - content: Custom error response parameters + content: Custom errors parameters --- -Custom Error Responses have the following parameters: +Custom Errors have the following parameters: - **`content`** String Required - - The response body to return. It can include [error tokens](/rules/custom-error-responses/error-tokens/) that will be replaced with real values before sending the error response to the visitor. + - 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. - The maximum content size is 10 KB. - **`content_type`** String Required diff --git a/src/content/docs/rules/index.mdx b/src/content/docs/rules/index.mdx index 7148f8ce42c6aea..05e17547e870fe4 100644 --- a/src/content/docs/rules/index.mdx +++ b/src/content/docs/rules/index.mdx @@ -79,12 +79,12 @@ Rules features require that you [proxy the DNS records](/dns/manage-dns-records/ - Define custom responses for errors returned by an origin server or by a - Cloudflare product, including Workers. + Define what custom content to serve for errors returned by an origin server + or by a Cloudflare product, including Workers. --- diff --git a/src/content/docs/rules/reference/esc-deprecation.mdx b/src/content/docs/rules/reference/esc-deprecation.mdx index 9e33e0471de0200..a1e4183317ab941 100644 --- a/src/content/docs/rules/reference/esc-deprecation.mdx +++ b/src/content/docs/rules/reference/esc-deprecation.mdx @@ -6,7 +6,6 @@ sidebar: head: - tag: title content: Deprecation notice for Edge Side Code - --- Edge Side Code (ESC) is a customization option used by several Enterprise customers that allows for more configurability of Cloudflare's global network features. This code can alter the behavior of Cloudflare's CDN, enabling logic for specific customer use cases. Currently, a few customers have ESC in place to perform special operations such as advanced header manipulation, host header switching. @@ -21,8 +20,6 @@ If your account is currently using ESC, your account team will contact you so th The following table contains recommendations for different use cases of ESC: - - | Use case | Description | Alternative | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Redirect to URL | Navigate visitors to a different URL without sending the request to the origin server. | Use [Single Redirects](/rules/url-forwarding/single-redirects/) or [Bulk Redirects](/rules/url-forwarding/bulk-redirects/). | @@ -31,29 +28,27 @@ The following table contains recommendations for different use cases of ESC: | Rewrite URI | Request a different URL from the origin server while displaying the original request URL in the visitor's browser. | Use [Transform Rules](/rules/transform/url-rewrite/) to rewrite URLs. | | Set/clear request headers | Set (or clear) HTTP headers sent to the origin server. | Use [Transform Rules](/rules/transform/request-header-modification/) to modify request headers. | | Feature exceptions | Exclude specific requests from one or more Cloudflare security products. | Use [Configuration Rules](/rules/configuration-rules/settings/). | -| Send custom error response | Abort the current request, returning a specific response body and/or HTTP status code to the client. | Use [Custom Error Responses](/rules/custom-error-responses/) to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). | +| Send custom error response | Abort the current request, returning a specific response body and/or HTTP status code to the client. | Use [Custom Error Responses](/rules/custom-errors/) to define custom responses for errors returned by an origin server or by a Cloudflare product (including Workers). | | Set/add/remove response headers | Update, add, or remove headers from the response returned by the origin server. | Use [Transform Rules](/rules/transform/response-header-modification/) to modify response headers. | | Status redirect | After receiving a response from the origin, conditionally send a redirect back to the client if the origin response code matches a key in the supplied table. | Use [Cloudflare Workers](/workers/). Refer to the [Modify response](/workers/examples/modify-response/) example for a similar use case. | | Add cookies to response | Set cookies in the response sent to the client. | Use [Transform Rules](/rules/transform/response-header-modification/) to modify response headers (which includes setting cookies). | - - For more complex use cases, consider using [Cloudflare Workers](/workers/). ## Can I disable ESC right now to understand the deprecation impact? Yes, you can [disable ESC via API](#disabling-esc-via-api). The API allows you to: -* Understand the impact of disabling ESC on your account or zone. -* Test your alternative configuration with other Cloudflare products (and with ESC disabled) before the sunset date. +- Understand the impact of disabling ESC on your account or zone. +- Test your alternative configuration with other Cloudflare products (and with ESC disabled) before the sunset date. ## What kind of tests can I run? The [available API operations](#api-operations) allow you to do the following: -* **Disable ESC for individual requests:** Any test requests containing a cookie with a specific secret will be processed with ESC disabled. -* **Disable/enable ESC for a specific zone:** After disabling ESC for a zone, all incoming requests for the zone will have all ESC configurations disabled. -* **Disable/enable ESC for an entire account**: After disabling ESC for an account, all incoming requests for any zone in the account will have all ESC configurations disabled. +- **Disable ESC for individual requests:** Any test requests containing a cookie with a specific secret will be processed with ESC disabled. +- **Disable/enable ESC for a specific zone:** After disabling ESC for a zone, all incoming requests for the zone will have all ESC configurations disabled. +- **Disable/enable ESC for an entire account**: After disabling ESC for an account, all incoming requests for any zone in the account will have all ESC configurations disabled. ## What is the recommended testing strategy? @@ -65,7 +60,7 @@ If these tests are successful, [disable ESC for the entire zone](#disable-esc-fo If you wish, you can also [disable ESC for an entire account](#disable-esc-for-an-account). This will affect all incoming requests for all zones in your account. -*** +--- ## Disabling ESC via API @@ -83,18 +78,16 @@ To disable/enable ESC for individual requests, do the following: To change the ESC status for a zone, use the following operations: -* [Disable ESC for a zone](#disable-esc-for-a-zone) -* [Re-enable ESC for a zone](#re-enable-esc-for-a-zone) +- [Disable ESC for a zone](#disable-esc-for-a-zone) +- [Re-enable ESC for a zone](#re-enable-esc-for-a-zone) To change the ESC status for an account, use the following operations: -* [Disable ESC for an account](#disable-esc-for-an-account) -* [Re-enable ESC for an account](#re-enable-esc-for-an-account) +- [Disable ESC for an account](#disable-esc-for-an-account) +- [Re-enable ESC for an account](#re-enable-esc-for-an-account) ### API operations - - | Name | HTTP verb | Endpoint | | --------------------------------------- | --------- | ------------------------------------ | | Get ESC secret or status for a zone | GET | `/zones/{zone_id}/disable_esc` | @@ -106,8 +99,6 @@ To change the ESC status for an account, use the following operations: | Disable ESC for an account | POST | `/accounts/{account_id}/disable_esc` | | Re-enable ESC for an account | DELETE | `/accounts/{account_id}/disable_esc` | - - To invoke an API operation, append the operation endpoint to the Cloudflare API base URL: ```txt @@ -129,13 +120,13 @@ curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/disable_esc" \ The following example response states that ESC is disabled for the entire `{zone_id}` zone: ```json -{"always": true} +{ "always": true } ``` The following example response includes the previously configured secret for the zone using the [Create ESC secret for a zone](#create-esc-secret-for-a-zone) operation: ```json -{"with_secret": ""} +{ "with_secret": "" } ``` #### Create ESC secret for a zone @@ -252,7 +243,7 @@ curl --request DELETE \ --header "X-Auth-Email: " ``` -*** +--- ## Final remarks diff --git a/src/content/docs/ruleset-engine/reference/phases-list.mdx b/src/content/docs/ruleset-engine/reference/phases-list.mdx index 8b11f8f9aa3d0d2..969d8523f2555e2 100644 --- a/src/content/docs/ruleset-engine/reference/phases-list.mdx +++ b/src/content/docs/ruleset-engine/reference/phases-list.mdx @@ -61,7 +61,7 @@ The phases execute in the order they appear in the table. | Phase name | Used in product/feature | | --------------------------------- | ----------------------------------------------------------------------------------------- | -| `http_custom_errors` | [Custom Error Responses](/rules/custom-error-responses/) | +| `http_custom_errors` | [Custom Errors](/rules/custom-errors/) | | _N/A_ (internal phase) | [Managed Transforms](/rules/transform/managed-transforms/) | | `http_response_headers_transform` | [HTTP Response Header Modification Rules](/rules/transform/response-header-modification/) | | `http_ratelimit` | [Rate limiting rules](/waf/rate-limiting-rules/) (when they use response information) | diff --git a/src/content/fields/index.yaml b/src/content/fields/index.yaml index 4788bfacb9fd4f9..2e910643265cbb6 100644 --- a/src/content/fields/index.yaml +++ b/src/content/fields/index.yaml @@ -1836,7 +1836,7 @@ entries: For a list of 1XXX errors, refer to [Troubleshooting Cloudflare 1XXX errors](/support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-1xxx-errors/). - **Note**: This field is only available in [HTTP response header modifications](/rules/transform/response-header-modification/) and [Custom Error Responses](/rules/custom-error-responses/). + **Note**: This field is only available in [HTTP response header modifications](/rules/transform/response-header-modification/) and [Custom Errors](/rules/custom-errors/). example_value: |- 1020 @@ -1863,4 +1863,4 @@ entries: You can use this field to customize the response for a specific type of error (for example, all 1XXX errors or all WAF block actions). - **Note**: This field is only available in [HTTP response header modifications](/rules/transform/response-header-modification/) and [Custom Error Responses](/rules/custom-error-responses/). + **Note**: This field is only available in [HTTP response header modifications](/rules/transform/response-header-modification/) and [Custom Errors](/rules/custom-errors/). diff --git a/src/content/partials/fundamentals/zone-permissions-table.mdx b/src/content/partials/fundamentals/zone-permissions-table.mdx index e9b7f8d84163fc2..6a7d0b25597c532 100644 --- a/src/content/partials/fundamentals/zone-permissions-table.mdx +++ b/src/content/partials/fundamentals/zone-permissions-table.mdx @@ -20,15 +20,15 @@ import { Markdown } from "~/components" | Bot Management Feedback {props.one} | Grants write access to [Bot Management feedback](/bots/concepts/feedback-loop/). | | Cache Purge | Grants access to [purge cache](/cache/how-to/purge-cache/). | | Cache Rules Read | Grants read access to [Cache Rules](/cache/how-to/cache-rules/). | -| Cache Rules {props.one} | Grants write access to [Cache Rules](/cache/how-to/cache-rules/). +| Cache Rules {props.one} | Grants write access to [Cache Rules](/cache/how-to/cache-rules/). | | Cloud Connector Read | Grants read access to [Cloud Connector rules](/rules/cloud-connector/). | | Cloud Connector {props.one} | Grants write access to [Cloud Connector rules](/rules/cloud-connector/). | | | Config Rules Read | Grants read access to [Configuration Rules](/rules/configuration-rules/). | | Config Rules {props.one} | Grants write access to [Configuration Rules](/rules/configuration-rules/). | -| Custom Errors Read | Grants read access to [Custom Errors Phase](/rules/custom-error-responses/create-api/). | -| Custom Errors {props.one} | Grants write access to [Custom Errors Phase](/rules/custom-error-responses/create-api/). | -| Custom Error Rules Read | Grants read access to [Custom Error Rules](/rules/custom-error-responses/). | -| Custom Error Rules {props.one} | Grants write access to [Custom Error Rules](/rules/custom-error-responses/). | +| Custom Errors Read | Grants read access to [Custom Errors phase](/rules/custom-errors/create-api/). | +| Custom Errors {props.one} | Grants write access to [Custom Errors phase](/rules/custom-errors/create-api/). | +| Custom Error Rules Read | Grants read access to [Custom Error Rules](/rules/custom-errors/). | +| Custom Error Rules {props.one} | 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.one} | Grants write access to [Custom Pages](/support/more-dashboard-apps/cloudflare-custom-pages/configuring-custom-pages-error-and-challenge/). | | DMARC Management Read | Grants read access to [DMARC Management](/dmarc-management/). | From 0884e0847a917dac24d08cb3889ee4bb59b02d2c Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Mon, 10 Feb 2025 14:55:57 +0000 Subject: [PATCH 2/8] Remove empty lines --- src/content/docs/rules/custom-errors/error-tokens.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/content/docs/rules/custom-errors/error-tokens.mdx b/src/content/docs/rules/custom-errors/error-tokens.mdx index b29959b69b37c3b..947ea1951e7907a 100644 --- a/src/content/docs/rules/custom-errors/error-tokens.mdx +++ b/src/content/docs/rules/custom-errors/error-tokens.mdx @@ -6,16 +6,12 @@ sidebar: head: - tag: title content: Custom error tokens - --- A custom error 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. | - From cce8c56227b2597bca87ead99714ed80b08b377f Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Mon, 10 Feb 2025 14:56:08 +0000 Subject: [PATCH 3/8] Update parameter reference --- .../docs/rules/custom-errors/parameters.mdx | 50 +++++++++++++++++-- 1 file changed, 46 insertions(+), 4 deletions(-) diff --git a/src/content/docs/rules/custom-errors/parameters.mdx b/src/content/docs/rules/custom-errors/parameters.mdx index c7f61fbcf6ec926..5e641c30c795d07 100644 --- a/src/content/docs/rules/custom-errors/parameters.mdx +++ b/src/content/docs/rules/custom-errors/parameters.mdx @@ -8,14 +8,27 @@ head: content: Custom errors parameters --- -Custom Errors have the following parameters: +import { Type, MetaInfo } from "~/components"; -- **`content`** String Required +## Custom error rules + +Custom error rules define when a custom error is triggered and what content to serve. + +Rule parameters are the following: + +- **`asset_name`** + + - The name of the [custom error asset](#custom-error-assets) you previously uploaded. It may 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 asset size is 1.5 MB. + +- **`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 an `asset_name` parameter or a `content` parameter. - The maximum content size is 10 KB. -- **`content_type`** String Required +- **`content_type`** - The content type of the returned response. Must be one of the following: @@ -24,7 +37,7 @@ Custom Errors have the following parameters: - `application/json` - `text/xml` -- **`status_code`** Integer Optional +- **`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`. @@ -37,3 +50,32 @@ If you create an HTML error response, make sure the `referrer` meta tag is not p ``` ::: + +## Custom error assets + +A custom error asset corresponds to a full HTML page (including images, CSS, and JavaScript code) collected by Cloudflare based on a URL you provide, to be served to visitors as an error page. You can use a custom error asset in [custom error rules](#custom-error-rules) as the error response that will be served to visitors under certain conditions. Those conditions are defined in the expression of the custom error rule. + +Custom error assets have the following parameters: + +- **`name`** + + - The name of the custom error asset. + - 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. + - Example value: `"500_error_template"`. + +- **`description`** + + - A string describing the custom error asset. + - Example value: `"Standard 5xx error template page"`. + +- **`url`** + + - The URL of the error page you want to store at Cloudflare to be served to visitors according to your [custom error rules](#custom-error-rules). + - When you create or update an asset and provide a URL, Cloudflare collects the images, CSS, and JavaScript code used in the page, minifies the content, and saves it internally. + - The HTML 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. + - Example value: `"https://example.com/errors/500.html"`. From 4ad44ee8ca2cdc97254bfbcacb28873a94bab85e Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Mon, 10 Feb 2025 19:25:16 +0000 Subject: [PATCH 4/8] Update API page --- .../docs/rules/custom-errors/create-api.mdx | 231 ++++++++++++++++-- 1 file changed, 211 insertions(+), 20 deletions(-) diff --git a/src/content/docs/rules/custom-errors/create-api.mdx b/src/content/docs/rules/custom-errors/create-api.mdx index 01cf5974e7f40b5..a44da82a58057d4 100644 --- a/src/content/docs/rules/custom-errors/create-api.mdx +++ b/src/content/docs/rules/custom-errors/create-api.mdx @@ -1,49 +1,216 @@ --- -title: Create via API +title: Create custom errors via API pcx_content_type: how-to sidebar: order: 2 + label: Create via API head: - tag: title - content: Create a custom error response via API + content: Create custom errors via API --- -Configure Custom Error Responses as [rules](/ruleset-engine/about/rules/) belonging to the `http_custom_errors` phase. Use the [Rulesets API](/ruleset-engine/rulesets-api/) to create Custom Error Responses via API. +To configure custom errors via API: -## Basic rule settings +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/). -When creating a custom error response via API, make sure you: +## Custom error assets -- Set the rule action to `serve_error`. -- Define the [parameters](/rules/custom-errors/parameters/) in the `action_parameters` field according to response type. -- Deploy the custom error response rule to the `http_custom_errors` phase at the zone level. +The following sections provide examples of common API calls for managing custom error assets at the zone level. -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. +To perform the same operations at the account level, use the corresponding account-level API endpoints. -## Procedure +### Create a custom error asset -Follow this workflow to create a custom error response rule for a given zone via API: +The following `POST` request creates new a custom error asset in a zone: -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. +```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" +}' +``` - 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. +```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 -## Example API calls +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 '{ + "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 +} +``` + +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 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} +``` -The examples in this section use the following fields in their rule expressions: +### 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 error 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/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/) and [1xxx](/support/troubleshooting/cloudflare-errors/troubleshooting-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`. ```bash curl --request PUT \ -https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom_errors/entrypoint \ +"https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom_errors/entrypoint" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ @@ -70,7 +237,7 @@ This example configures a custom HTML error response for responses with a `500` ```bash curl --request PUT \ -https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom_errors/entrypoint \ +"https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom_errors/entrypoint" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data '{ @@ -117,9 +284,33 @@ https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom 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. + +```bash +curl --request PUT \ +"https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom_errors/entrypoint" \ +--header "Authorization: Bearer " \ +--header "Content-Type: application/json" \ +--data '{ + "rules": [ + { + "action": "serve_error", + "action_parameters": { + "asset_name": "500_error_template", + "content_type": "text/html" + }, + "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. -## ​​Required API token permissions +## Required API token permissions The API token used in API requests to manage Custom Error Responses must have at least the following permission: From d78cfb6d3317a600c43d8826c3a4825f0250bb47 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Mon, 10 Feb 2025 19:25:34 +0000 Subject: [PATCH 5/8] Review parameters page --- .../docs/rules/custom-errors/parameters.mdx | 31 ++++++------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/src/content/docs/rules/custom-errors/parameters.mdx b/src/content/docs/rules/custom-errors/parameters.mdx index 5e641c30c795d07..7abcd3874dd8c76 100644 --- a/src/content/docs/rules/custom-errors/parameters.mdx +++ b/src/content/docs/rules/custom-errors/parameters.mdx @@ -12,31 +12,24 @@ import { Type, MetaInfo } from "~/components"; ## Custom error rules -Custom error rules define when a custom error is triggered and what content to serve. +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. It may include [error tokens](/rules/custom-errors/error-tokens/) that will be replaced with real values before sending the error response to the visitor. + - 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. - - The maximum asset size is 1.5 MB. - - **`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 an `asset_name` parameter or a `content` parameter. + - 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`. @@ -58,24 +51,20 @@ A custom error asset corresponds to a full HTML page (including images, CSS, and 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`) + - Numbers (`0-9`) - The underscore (`_`) character - - The maximum length is 200 characters. - - Example value: `"500_error_template"`. - + - 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 error page you want to store at Cloudflare to be served to visitors according to your [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 the images, CSS, and JavaScript code used in the page, minifies the content, and saves it internally. - - The HTML 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. + - The HTML 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. - - Example value: `"https://example.com/errors/500.html"`. + - The maximum asset size is 1.5 MB. From 09e573ed64430185a1257f9ac3ee23b2d905f509 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Tue, 11 Feb 2025 12:46:35 +0000 Subject: [PATCH 6/8] Small updates --- .../docs/rules/custom-errors/create-api.mdx | 16 +++++++++------- .../docs/rules/custom-errors/error-tokens.mdx | 2 +- src/content/docs/rules/custom-errors/index.mdx | 10 ++-------- .../docs/rules/custom-errors/parameters.mdx | 10 +++++----- 4 files changed, 17 insertions(+), 21 deletions(-) diff --git a/src/content/docs/rules/custom-errors/create-api.mdx b/src/content/docs/rules/custom-errors/create-api.mdx index a44da82a58057d4..e7a6b8b5f2ea82b 100644 --- a/src/content/docs/rules/custom-errors/create-api.mdx +++ b/src/content/docs/rules/custom-errors/create-api.mdx @@ -22,7 +22,7 @@ To perform the same operations at the account level, use the corresponding accou ### Create a custom error asset -The following `POST` request creates new a custom error asset in a zone: +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" \ @@ -72,7 +72,7 @@ curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets" "url": "https://example.com/errors/500_template.html", "last_updated": "2025-02-10T11:36:07.810215Z", "size_bytes": 2048 - }, + } // ... ], "success": true, @@ -121,6 +121,8 @@ curl --request PUT \ } ``` +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: @@ -131,7 +133,7 @@ https://api.cloudflare.com/client/v4/accounts/{account_id}/custom_pages/assets/{ ### Get a custom error asset -The following `GET` request retrieves an existing custom error asset at the zone level named `500_error_template`: +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" \ @@ -189,9 +191,9 @@ The first rule in the `http_custom_errors` phase ruleset that matches will be ap 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 error response for error codes returned by the origin server or by a Cloudflare product such as a Worker. +- [`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/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/) and [1xxx](/support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-1xxx-errors/). +- [`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/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/) and [1XXX](/support/troubleshooting/cloudflare-errors/troubleshooting-cloudflare-1xxx-errors/). ### General procedure @@ -204,9 +206,9 @@ Follow this workflow to create a custom error rule for a given zone via API: To create a custom error rule at the account level, use the corresponding account-level API endpoints. -### Custom JSON response for all 5xx errors +### 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 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`. ```bash curl --request PUT \ diff --git a/src/content/docs/rules/custom-errors/error-tokens.mdx b/src/content/docs/rules/custom-errors/error-tokens.mdx index 947ea1951e7907a..6673d8b1e8f8116 100644 --- a/src/content/docs/rules/custom-errors/error-tokens.mdx +++ b/src/content/docs/rules/custom-errors/error-tokens.mdx @@ -8,7 +8,7 @@ head: content: Custom error tokens --- -A custom error may include the following error tokens, which will be replaced with their real values before sending the response to the visitor: +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 | | --------------- | ------------------------------------------------------------------------ | diff --git a/src/content/docs/rules/custom-errors/index.mdx b/src/content/docs/rules/custom-errors/index.mdx index 04cb44a398181f0..833ae2067056623 100644 --- a/src/content/docs/rules/custom-errors/index.mdx +++ b/src/content/docs/rules/custom-errors/index.mdx @@ -18,16 +18,12 @@ To configure a custom error, create a custom error rule at the account or zone l Custom Errors require that you [proxy the DNS records](/dns/manage-dns-records/reference/proxied-dns-records/) of your domain (or subdomain) through Cloudflare. :::note[Notes about the beta] - -During the beta, you can define a custom error using a URL or an inline template, and specify the response's content type and HTTP status code. - -Additionally, at this stage you can only create custom error rules [using the API](/rules/custom-errors/create-api/). - +During the beta you can only create custom error rules [using the API](/rules/custom-errors/create-api/). ::: ## How it works -When defining the custom error to serve, you provide either the URL of an existing HTML page or inline HTML content. When you provide a URL, Cloudflare will gather the required images, CSS, and JavaScript code and save a minified version of the full page. This full page is called a custom error asset, which you can use in one or more custom error rules in same scope of the asset (zone or account). +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, which you can use in one or more custom error rules in same scope of the asset (zone or account). When a custom error is triggered, Cloudflare will replace the body with the response you previously defined and (optionally) the response HTTP status code sent to the visitor. @@ -44,5 +40,3 @@ Custom Errors are available in beta to all paid plans. The exact features depend | Custom Errors | No | Yes | Yes | Yes | | Number of custom error rules | — | 5 | 20 | 50 | | Number of custom error assets | — | 5 | 20 | 50 | - -The size limit of each custom error asset is 1.5 MB. diff --git a/src/content/docs/rules/custom-errors/parameters.mdx b/src/content/docs/rules/custom-errors/parameters.mdx index 7abcd3874dd8c76..d3c22ec80537cee 100644 --- a/src/content/docs/rules/custom-errors/parameters.mdx +++ b/src/content/docs/rules/custom-errors/parameters.mdx @@ -18,7 +18,7 @@ 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). + - 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. @@ -46,7 +46,7 @@ If you create an HTML error response, make sure the `referrer` meta tag is not p ## Custom error assets -A custom error asset corresponds to a full HTML page (including images, CSS, and JavaScript code) collected by Cloudflare based on a URL you provide, to be served to visitors as an error page. You can use a custom error asset in [custom error rules](#custom-error-rules) as the error response that will be served to visitors under certain conditions. Those conditions are defined in the expression of the custom error rule. +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: @@ -62,9 +62,9 @@ Custom error assets have the following parameters: - A string describing the custom error asset. - Example value: `"Standard 5xx error template page"`. - **`url`** - - The URL of the error page you want to store at Cloudflare to be served to visitors according to your [custom error rules](#custom-error-rules). + - 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 the images, CSS, and JavaScript code used in the page, minifies the content, and saves it internally. - - The HTML 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. + - 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. From bac6f6c47d16872b79c027efb2e5a18420a361c9 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Tue, 11 Feb 2025 14:47:02 +0000 Subject: [PATCH 7/8] Small fixes --- src/content/docs/rules/custom-errors/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/rules/custom-errors/index.mdx b/src/content/docs/rules/custom-errors/index.mdx index 833ae2067056623..6c17b451b272b11 100644 --- a/src/content/docs/rules/custom-errors/index.mdx +++ b/src/content/docs/rules/custom-errors/index.mdx @@ -11,9 +11,9 @@ head: content: Custom Errors (beta) --- -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. +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. -To configure a custom error, create a custom error rule at the account or zone level. 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. +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. Custom Errors require that you [proxy the DNS records](/dns/manage-dns-records/reference/proxied-dns-records/) of your domain (or subdomain) through Cloudflare. @@ -23,9 +23,9 @@ During the beta you can only create custom error rules [using the API](/rules/cu ## 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, which you can use in one or more custom error rules in same scope of the asset (zone or account). +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). -When a custom error 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 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`. From e81627f28c477c5e11e30e5c54c04a80e04f8672 Mon Sep 17 00:00:00 2001 From: Pedro Sousa <680496+pedrosousa@users.noreply.github.com> Date: Tue, 11 Feb 2025 14:47:17 +0000 Subject: [PATCH 8/8] Add release note and changelog entry --- .../2025-02-11-custom-errors-beta.mdx | 50 +++++++++++++++++++ src/content/changelogs/rules.yaml | 4 ++ 2 files changed, 54 insertions(+) create mode 100644 src/content/changelogs-next/2025-02-11-custom-errors-beta.mdx diff --git a/src/content/changelogs-next/2025-02-11-custom-errors-beta.mdx b/src/content/changelogs-next/2025-02-11-custom-errors-beta.mdx new file mode 100644 index 000000000000000..ae0aa9b02b20d3a --- /dev/null +++ b/src/content/changelogs-next/2025-02-11-custom-errors-beta.mdx @@ -0,0 +1,50 @@ +--- +title: "Custom Errors (beta): Stored Assets & Account-level Rules" +description: Cloudflare introduces Custom Errors (beta), building on Custom Error Responses with new asset storage capabilities +products: + - rules +date: 2025-02-11T11:00:00Z +--- + +Cloudflare introduces [Custom Errors](/rules/custom-errors/) (beta), building on Custom Error Responses with new asset storage capabilities. This update allows users to store externally hosted error pages at Cloudflare edge and reference them in custom error rules, eliminating the need to supply inline content. + +New capabilities: + +- **Custom error assets** – Fetch and store external error pages at the edge for use in error responses. +- **Account-Level custom errors** – Define error handling rules and assets at the account level for consistency across multiple zones. Zone-level rules take precedence over account-level ones, and assets are not shared between levels. + +To store an external error page on the Cloudflare global network, submit a `POST` request to create an asset: + +```bash +curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_pages/assets" \ +--header "Authorization: Bearer " \ +--header 'Content-Type: application/json' \ +--data '{ + "name": "maintenance", + "description": "Maintenance template page", + "url": "https://example.com/" +}' +``` + +Then, reference the stored asset in a custom error rule: + +```bash +curl --request PUT \ +"https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_custom_errors/entrypoint" \ +--header "Authorization: Bearer " \ +--header 'Content-Type: application/json' \ +--data '{ + "rules": [ + { + "action": "serve_error", + "action_parameters": { + "asset_name": "maintenance", + "content_type": "text/html", + "status_code": 503 + }, + "enabled": true, + "expression": "http.request.uri.path contains \"error\"" + } + ] +}' +``` diff --git a/src/content/changelogs/rules.yaml b/src/content/changelogs/rules.yaml index 1b55e3f79a5100b..1a2ec3402ff6dde 100644 --- a/src/content/changelogs/rules.yaml +++ b/src/content/changelogs/rules.yaml @@ -5,6 +5,10 @@ productLink: "/rules/" productArea: Application performance productAreaLink: /fundamentals/reference/changelog/performance/ entries: + - publish_date: "2025-02-11" + title: "Custom Errors (beta): Stored assets and account-level rules" + description: |- + Cloudflare introduces [Custom Errors](/rules/custom-errors/) (beta), expanding on Custom Error Responses with new asset storage capabilities. With custom error assets, you can now retrieve and store externally hosted error pages at Cloudflare edge and reference them in custom error rules, eliminating the need to define error content inline. Additionally, Custom Errors now support account-level rules and assets, enabling consistent error handling across multiple zones. - publish_date: "2025-01-29" title: New Snippets code editor description: |-