Skip to content

[Rules] Update error page types #22830

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 4, 2025
Merged

[Rules] Update error page types #22830

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
beaafc3
[Rules] Update error page types
pedrosousa Jun 2, 2025
59562a2
Adjust sentence
pedrosousa Jun 2, 2025
592827b
Add error page example API calls
pedrosousa Jun 3, 2025
a0482f3
Add API identifiers to page types list
pedrosousa Jun 3, 2025
ff28fb3
Fix typo
pedrosousa Jun 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions src/content/docs/rules/custom-errors/api-calls.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ head:
content: Common API calls | Custom Error Assets
---

import { APIRequest } from "~/components";

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.
Expand Down Expand Up @@ -167,3 +169,75 @@ 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
```

### Get error page

This example obtains the current configuration for the `Rate limiting block` error page (with ID `ratelimit_block`).

<APIRequest
path="/zones/{zone_identifier}/custom_pages/{identifier}"
method="GET"
parameters={{
identifier: "ratelimit_block",
}}
/>

```json output
{
"result": {
"id": "ratelimit_block",
"description": "Rate limit Block",
"required_tokens": [],
"preview_target": "block:rate-limit",
"created_on": "2025-06-03T08:33:17.091587Z",
"modified_on": "2025-06-03T08:33:17.091587Z",
"url": null,
"state": "default"
},
"success": true,
"errors": [],
"messages": []
}
```

The response indicates that the page is currently set to the Cloudflare default page (`"state": "default"`).

For a list of error page identifiers, refer to [Error page types](/rules/custom-errors/reference/error-page-types/).

### Update error page

This example defines a custom error page for `Rate limiting block` errors (with ID `ratelimit_block`) based on the provided URL.

<APIRequest
path="/zones/{zone_identifier}/custom_pages/{identifier}"
method="PUT"
parameters={{
identifier: "ratelimit_block",
}}
json={{
state: "customized",
url: "https://example.com/rate_limiting_block_error_page.html",
}}
/>

```json output
{
"result": {
"id": "ratelimit_block",
"description": "Rate limit Block",
"required_tokens": [],
"preview_target": "block:rate-limit",
"created_on": "2025-06-03T08:33:17.091587Z",
"modified_on": "2025-06-03T08:35:32.639114Z",
"url": "https://example.com/rate_limiting_block_error_page.html",
"state": "customized"
},
"success": true,
"errors": [],
"messages": []
}
```

To set the error page back to the default page, use `"state": "default"` in the request body.

For a list of error page identifiers, refer to [Error page types](/rules/custom-errors/reference/error-page-types/).
2 changes: 1 addition & 1 deletion src/content/docs/rules/custom-errors/edit-error-pages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Before defining a custom error page in your Cloudflare account, you will need to

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.
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 **WAF block**, you must design and publish two separate pages.

:::note[Notes]

Expand Down
27 changes: 18 additions & 9 deletions src/content/docs/rules/custom-errors/reference/error-page-types.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,21 @@ 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. |
| Page type | Description | API identifier |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| WAF block | The page displayed when visitors are blocked by a [Web Application Firewall](/waf/) rule. This page returns a `403` status code. | `waf_block` |
| 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_block` |
| 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/). | `country_challenge` |
| 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/). | `500_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/). | `1000_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/). | `managed_challenge` |
| 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. | `ratelimit_block` |

The following error page types will only be shown in the Cloudflare dashboard if you have customized their error pages in the past:

| Page type | API identifier |
| --------------------- | ----------------- |
| Interactive Challenge | `basic_challenge` |
| JavaScript Challenge | `under_attack` |

These types of challenges are being discouraged in favor of managed challenges. Refer to [Challenge pages](/cloudflare-challenges/challenge-types/challenge-pages/) for more information.
Loading