Skip to content

Commit d12eefe

Browse files
pedrosousapedrosousa
authored
[Rules] Update error page types (#22830)
* [Rules] Update error page types * Adjust sentence * Add error page example API calls * Add API identifiers to page types list * Fix typo
1 parent 5dab63c commit d12eefe

File tree

3 files changed

+93
-10
lines changed

3 files changed

+93
-10
lines changed

‎src/content/docs/rules/custom-errors/api-calls.mdx‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ head:
88
content: Common API calls | Custom Error Assets
99
---
1010

11+
import { APIRequest } from "~/components";
12+
1113
The following sections provide examples of common API calls for managing custom error assets at the zone level.
1214

1315
To perform the same operations at the account level, use the corresponding account-level API endpoints.
@@ -167,3 +169,75 @@ To delete an asset at the account level, use the account-level endpoint:
167169
```txt
168170
https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/custom_pages/assets/$ASSET_NAME
169171
```
172+
173+
### Get error page
174+
175+
This example obtains the current configuration for the `Rate limiting block` error page (with ID `ratelimit_block`).
176+
177+
<APIRequest
178+
path="/zones/{zone_identifier}/custom_pages/{identifier}"
179+
method="GET"
180+
parameters={{
181+
identifier: "ratelimit_block",
182+
}}
183+
/>
184+
185+
```json output
186+
{
187+
"result": {
188+
"id": "ratelimit_block",
189+
"description": "Rate limit Block",
190+
"required_tokens": [],
191+
"preview_target": "block:rate-limit",
192+
"created_on": "2025-06-03T08:33:17.091587Z",
193+
"modified_on": "2025-06-03T08:33:17.091587Z",
194+
"url": null,
195+
"state": "default"
196+
},
197+
"success": true,
198+
"errors": [],
199+
"messages": []
200+
}
201+
```
202+
203+
The response indicates that the page is currently set to the Cloudflare default page (`"state": "default"`).
204+
205+
For a list of error page identifiers, refer to [Error page types](/rules/custom-errors/reference/error-page-types/).
206+
207+
### Update error page
208+
209+
This example defines a custom error page for `Rate limiting block` errors (with ID `ratelimit_block`) based on the provided URL.
210+
211+
<APIRequest
212+
path="/zones/{zone_identifier}/custom_pages/{identifier}"
213+
method="PUT"
214+
parameters={{
215+
identifier: "ratelimit_block",
216+
}}
217+
json={{
218+
state: "customized",
219+
url: "https://example.com/rate_limiting_block_error_page.html",
220+
}}
221+
/>
222+
223+
```json output
224+
{
225+
"result": {
226+
"id": "ratelimit_block",
227+
"description": "Rate limit Block",
228+
"required_tokens": [],
229+
"preview_target": "block:rate-limit",
230+
"created_on": "2025-06-03T08:33:17.091587Z",
231+
"modified_on": "2025-06-03T08:35:32.639114Z",
232+
"url": "https://example.com/rate_limiting_block_error_page.html",
233+
"state": "customized"
234+
},
235+
"success": true,
236+
"errors": [],
237+
"messages": []
238+
}
239+
```
240+
241+
To set the error page back to the default page, use `"state": "default"` in the request body.
242+
243+
For a list of error page identifiers, refer to [Error page types](/rules/custom-errors/reference/error-page-types/).

‎src/content/docs/rules/custom-errors/edit-error-pages.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Before defining a custom error page in your Cloudflare account, you will need to
1313

1414
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.
1515

16-
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.
16+
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.
1717

1818
:::note[Notes]
1919

‎src/content/docs/rules/custom-errors/reference/error-page-types.mdx‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,21 @@ sidebar:
55
order: 4
66
---
77

8-
| Page type | Description |
9-
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10-
| WAF block | The page displayed when visitors are blocked by a [Web Application Firewall](/waf/) rule. This page returns a `403` status code. |
11-
| 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. |
12-
| 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/). |
13-
| 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/). |
14-
| 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/). |
15-
| 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/). |
16-
| 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. |
8+
| Page type | Description | API identifier |
9+
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
10+
| 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` |
11+
| IP/Country block | The page displayed when a request originates from a [blocked IP address or country](/waf/tools/ip-access-rules/). This page returns a `403` status code. | `ip_block` |
12+
| 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` |
13+
| 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` |
14+
| 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` |
15+
| 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` |
16+
| 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` |
17+
18+
The following error page types will only be shown in the Cloudflare dashboard if you have customized their error pages in the past:
19+
20+
| Page type | API identifier |
21+
| --------------------- | ----------------- |
22+
| Interactive Challenge | `basic_challenge` |
23+
| JavaScript Challenge | `under_attack` |
24+
25+
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.

0 commit comments

Comments
 (0)