Custom Pages response model
A Custom Page changes the body of a Cloudflare-generated response without changing the status or security action that produced it.
Which Cloudflare responses can be customized
Custom Pages replace the body of specific Cloudflare-generated responses, including challenge pages, WAF blocks, rate-limit blocks and selected origin-error pages. Each page type is independent. Customizing its HTML does not change the HTTP status, security action or origin failure that caused the response.
Plan availability
Custom Page types are available according to the active Cloudflare plan. When a type is not included, Cloudflare's default page remains active. Upgrade the zone plan only when the required response type and customization are justified; a custom page is presentation, not additional mitigation.
Template requirements
Each response type has its own source, required placeholders and plan availability.
Page source requirements
A custom page is supplied from an HTTPS URL. Host it independently from the application path whose failure it describes, and avoid dependencies on the same scripts, fonts, APIs or origin that may be unavailable. Keep the document small, accessible and useful without JavaScript.
Required placeholders
Cloudflare page types require exact placeholders so challenge widgets, error details or incident references can be inserted. Preserve every placeholder listed for the selected type, including punctuation and letter case. A missing or altered token can make the page invalid or prevent a visitor from completing a challenge.
- Challenge pages commonly require the CAPTCHA or challenge placeholder.
- Error pages can require an incident identifier or diagnostic token.
- Do not translate, HTML-escape or split a required placeholder.
Content, security and resilience
Failure content must remain usable when the protected application, its assets or a challenge flow is unavailable.
Write useful failure content
State whether the visitor should retry, wait, contact the site owner or check submitted data. Preserve a reference identifier when available. Do not promise a recovery time or expose origin addresses, rule expressions, internal hostnames or provider credentials.
Security and privacy
Custom HTML is public and can be shown during a security event. Do not include customer data, secrets or diagnostic dumps. Load no third-party analytics that could fail a challenge, leak the blocked URL or create a consent problem.
Testing and rollback
Trigger and verify the exact response type, then retain Cloudflare default content as the immediate recovery path.
Test the exact response type
Use a staging hostname or a narrowly scoped temporary rule to produce the selected response. Confirm HTTPS loading, required placeholders, keyboard use, mobile layout, status code and behaviour when external assets fail. Remove the temporary trigger immediately after testing.
Disabled controls and rollback
When the plan does not include a page type, its fields remain unavailable and the default page is served. To recover from invalid custom HTML or an unreachable page source, restore that type to Cloudflare default, then verify the original diagnostic response before editing the custom document again.
