How to Set Up Custom HTTP Error Pages on VergeCloud

Custom Error Pages

Overview 

The Custom Pages feature in VergeCloud CDN allows you to personalize the experience your users see whenever your website encounters service interruptions, maintenance periods, or protective security challenges. Instead of showing default VergeCloud system messages, you can replace them with your own branded HTML pages or configure redirects to other URLs.

Custom Pages can be used for:
  1. Error pages (4xx, 5xx)
  2. Under Construction / Maintenance pages
  3. Secure Link errors
  4. WAF and Firewall challenge/blocked pages
  5. DDoS challenge screens (JS/Captcha)
  6. Rate limit violation pages
This functionality ensures a seamless user experience while giving you full control over how your website communicates during errors or security events.

Real Usage Scenarios

Imagine your website goes down for maintenance. Instead of showing a generic error, you display a customized “Under Construction” page with branding, support links, or CTAs ensuring users know the downtime is intentional and temporary. Similarly, during DDoS protection, you can brand and style challenge pages for a consistent user experience.

Managing Custom Pages

You can manage Custom Pages under CDN → Custom Pages in the VergeCloud Dashboard.

You may:
Use Default Page – VergeCloud standard layout
Upload Your Own HTML – Fully customized page
Redirect Users – Forward visitors to another URL

HTML Template Starter Example

<html>
<head></head>
<body>
  %desired variable%
</body>
</html>

Important:
Any external resources (images, CSS, JS) must respond with 200 OK. If firewall or geo-restrictions block these URLs, your custom page may break. When using paths from your domain, ensure your firewall or WAF rules allow access.

For example, if you have an image file hosted on your domain and you restrict access from specific geographic regions at the domain level, you will need to adjust the paths for your static files to ensure that firewall rules do not interfere.

Available Variables

These dynamic variables can be used in any Custom Page to provide meaningful context

VariableDescription
%IP%User’s IP address
%SID%Server ID handling the request
%DOMAIN%Requested domain
%ERRCODE%Error code displayed to visitor
%TIME%Timestamp ( YYYY-MM-dd HH:mm:ss Z )
%REQUEST_ID%Unique request identifier
%Challenge%Inserts DDoS protection challenge logic dynamically

These variables help create dynamic, informative, and branded pages.
The image below illustrates some of the aforementioned values displayed on a 403 error page.

 

Finally, click on Save to apply the changes.

Under Construction Pages

This feature allows you to select which page visitors will see when the website is undergoing maintenance. Essentially, you can modify the page that users encounter while your site is being updated.

Be aware that by using either the Upload HTML or Redirect options, the "Under Maintenance" mode will be activated across your entire domain.

Setting a "Custom Page" for the Under Construction Page via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY ' \
--header 'cache-control: no-cache' \
--form 'file=@"/C:/Users/vergecloud/Desktop/example.html"' \
--form 'page="under_construction"' \
--form 'type="file"'

Setting the "Redirect" for the Under Construction Page via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'page="under_construction"' \
--form 'url="https://example.com/uc.html"' \
--form 'type="url"'

Error Page For Server Errors

This error indicates that the primary server is temporarily inaccessible. VergeCloud displays this message by default when the origin server returns any of the 500, 502, 503, or 504 error codes.

In such cases, users will see an error similar to the image below:

 

Set "Redirect" for Errors Connecting to the Main Server via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'page="error_500"' \
--form 'url="https://example.com/500"' \
--form 'type="url"'

"Upload HTML" for Errors Connecting to the Main Server via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'file=@"/C:/Users/vergecloud/Desktop/example.html"' \
--form 'page="error_500"' \
--form 'type="file"'

Custom Template for DDoS Protection Challenges

When activating either the JavaScript or Captcha challenges, a page will be shown to your visitors to verify that they are not automated systems. You can personalize these DDoS challenge pages using Custom Pages.

To create DDoS pages, ensure that you include the %Challenge% variable in the file you upload for the dedicated page.

JavaScript Challenge

By default, visitors will see a page like the one below for a JavaScript challenge:

 

Setting Up a Custom JavaScript Challenge Page via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'file=@"/path/to/file"' \
--form 'page="ddos_js"' \
--form 'type="file"'

Captcha Challenge

By default, visitors will encounter a page like the one below for a Captcha challenge:

 

Setting Up a Custom Captcha Challenge Page via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'file=@"/path/to/file"' \
--form 'page="ddos_captcha"' \
--form 'type="file"'

When activating the secure link feature on content, only users utilizing their encrypted and specially generated links can access the specified paths. These restrictions may be applied based on specific IP addresses and access durations.

If the user's identity cannot be validated according to the requested parameters, the following error will be displayed by default:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'page="secure_link_invalid"' \
--form 'url="https://example.com/securelink"' \
--form 'type="url"'
curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'file=@"/C:/Users/vergecloud/Desktop/example.html"' \
--form 'page="secure_link_invalid"' \
--form 'type="file"'

Firewall Errors

VergeCloud Firewall allows you to define security rules in a cloud environment and manage access to your content with a high level of security through various restrictions. You can designate which page your visitors will see when firewall errors occur.

The default error pages for VergeCloud’s firewall are illustrated below:

 

Configure Firewall Error "Redirect" via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'page="firewall_error"' \
--form 'url="https://example.com/firewall"' \
--form 'type="url"'

"Upload HTML" for Firewall Error via API:

curl --location --request GET 'https://api.vergecloud.com/v1domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'file=@"/C:/Users/vergecloud/Desktop/example.html"' \
--form 'page="firewall_error"' \
--form 'type="file"'

WAF Errors

The Web Application Firewall (WAF) is designed to monitor and block manipulated data packets targeting web applications.

The default error messages for this service are shown below:

 

Set "Redirect" for WAF Error via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'page="waf_protection"' \
--form 'url="https://example.com/waf"' \
--form 'type="url"'

"Upload HTML" for WAF Error via API:

curl --location --request GET 'https://api.vergecloud.com/v1domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'file=@"/C:/Users/vergecloud/Desktop/example.html"' \
--form 'page="waf_protection"' \
--form 'type="file"'

Rate Limit Errors

Rate Limiting allows you to control the incoming and outgoing traffic to and from a network by restricting the number of requests a user can send.

If a user exceeds the allowed traffic limits, they will encounter an error, which by default appears as shown below:

 

Set "Redirect" for Rate Limit Error via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'page="rate_limit_exceeded"' \
--form 'url="https://example.com/rl"' \
--form 'type="url"'

"Upload HTML" for Rate Limit Error via API:

curl --location --request GET 'https://api.vergecloud.com/v1/domains/example.com/custom-pages' \
--header 'authority: api.vergecloud.com' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: APIKEY 1 2 3 4' \
--header 'cache-control: no-cache' \
--form 'file=@"/C:/Users/vergecloud/Desktop/example.html"' \
--form 'page="rate_limit_exceeded"' \
--form 'type="file"'

Final Notes

  1. Custom Pages improve user experience during errors, attacks, and maintenance.
  2. All static resources referenced in your custom page must be publicly accessible.
  3. Ensure firewall, WAF, or geoblocking rules do not interfere with assets used in your custom HTML.
  4. Always test custom pages after uploading to ensure correct rendering.

    • Related Articles

    • Custom SSL Certificate

      Overview Custom SSL certificates play a crucial role in securing modern applications, ensuring encrypted communication between clients and servers. VergeCloud provides a robust and user-friendly interface that allows users to upload, manage, and ...

    • Boost Web Pages

      Overview Web Boost is designed to enhance the loading speed and overall performance of your website by optimizing static assets, images, and the delivery of code. In today’s digital landscape, speed is not just a convenience; it has a direct impact ...

    • Domain-Based and Organization-Based Roles

      Overview This platform uses a role-based access control (RBAC) system to manage what actions users can perform. Roles are divided into two main categories: Domain-Based Roles and Organization-Based Roles. Each role provides a specific set of ...

    • Page Rules

      Overview VergeCloud Page Rules allow you to customize and fine-tune how your domain behaves within the VergeCloud CDN ecosystem. They give you granular control over performance, security, caching, redirects, and request handling at the edge. Instead ...

    • Caching

      Overview Caching plays a crucial role in improving website performance by temporarily storing web content so it can be delivered faster and with less strain on your origin server. When caching is enabled through VergeCloud’s CDN, your content is ...