Customize an error page

Replace the error responses of a workload with your own pages, one per status code, each with its own cache time and response status code.

Last updated

View as Markdown Agent setup

You can replace the error responses of a workload with pages of your own, for several status codes at once, from Azion Console, the Azion CLI, or the API. To create your first set with one page and see it replace a 404, refer to Custom Pages quickstart.

With Custom Pages, the pages live in a custom page set. Each page answers one status code that the application’s connector returns, and the set serves pages only after the workload’s deployment names it.

An application that runs on API v3 sets its error pages in Error Responses instead. For more information, refer to Error Responses.

Prerequisites

Console

  • A workload and an application for it to serve. To create both, refer to Workloads quickstart.
  • A connector that serves your error page documents, each at its own path. For more information, refer to Connectors.
  • Access to Azion Console. For more information, refer to How to access Azion Console.
  • A workload whose deployment names the application.

Create a set with a page for each code

Each page in the set takes its own status code, connector path, cache time, and response status code. A page can also answer with a code other than the one the connector returned, such as a 404 in place of a 403. Azion serves the page in place, with no redirect. After you change a page’s document, Azion keeps serving the cached copy until its cache time runs out. For the codes a page accepts and the range of each field, refer to Custom page settings.

Console

To create the set in Azion Console:

Open the Custom Pages page

Access Azion Console > Custom Pages.

Start the set

Select Create Custom Page. To add pages to a set you already have, select that set instead.

Name the set

In Name, enter a name that identifies the set, such as my-error-pages.

Select Create Custom Page Code
Select the status code

In Page Code, select the status code your connector returns, such as 404.

Select the connector

In Connector, select the connector that holds the page.

Enter the page path

In Page Path (URI), enter the path of the page on the connector, such as /errors/404.html.

Set the cache time

In Response TTL, enter the number of seconds the page stays in cache, such as 3600.

(Optional) Set the response status code

In Response Custom Status Code, enter the status code the client receives instead of the original one.

Add the other codes

Select Create Custom Page Code again for each other status code, and fill in its fields the same way.

Save the set

Select Create. On a set you already have, select Save.

The Page Codes table lists one row per page, with its Page Status Code, Page Path (URI), Custom Status Code, and Response TTL.

Assign the set in the workload’s deployment

The deployment of a workload names its application, its firewall, and its custom page set. Only the custom page set changes here, so the application and the firewall keep the values the workload uses today.

Console

To assign the set in Azion Console:

Open the Workloads page

Access Azion Console > Workloads.

Open the workload

Select the workload whose error responses the set replaces. Its edit form opens.

Select your set

In the Deployment Settings section, select your set in the Custom Page field. In a workload with no set, the field reads Select a custom page.

Application and Firewall keep the values the workload serves today.

Save the workload

Select Save.

Azion Console shows “Your workload has been updated”, and the deployment of the workload names your set.

Confirm that a page replaces the error

The check is the same for every interface. A change to a workload’s deployment takes several minutes to reach all of Azion’s distributed infrastructure, and requests can receive the previous or the updated configuration meanwhile. Repeat a request until the answers agree.

Request a path for which your connector returns a status code the set covers. Replace <your-domain> with a domain the workload serves, such as its workload domain of the form <id>.map.azionedge.net:

curl -s -D - https://<your-domain>/<missing-path>

For a page whose response status code is 404, the response starts with this status line, followed by the headers your connector sends and the document at the page’s path:

HTTP/2 404

The response carries no Location header, so the client stays on the requested URL and is not redirected. If the connector’s own error response still arrives after the deployment change has spread, refer to Troubleshoot Workloads.

Next steps

Custom page settingsLook up every status code a page accepts, the range of each field, and the API errors.How Workloads worksFollow a response from the connector's status code to the page the client receives.Workload settingsCheck every field of the deployment that names the application, firewall, and custom page set.Troubleshoot WorkloadsFind why a workload still returns the connector's error response instead of your page.