Custom Error Pages

Last edit: Jun 24, 2022

Instead of returning standard error pages, you can set up custom error pages that match your site's design and include information you'd like to convey to your users (e.g. helpful content, relevant links, encouragement to search or browse further).

You can customize the following error pages:

  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Server Error
  • 503 - Maintenance

Creating a custom error page

Error pages are normal platformOS pages, so you can use all features of a page (e.g. layouts). To create a customized error page, create a Page and set the file name to the status code.


layout: error_page
The resource you were looking for does not exist.

Error pages

Status Code Name Usage
403 Forbidden Solely used for a violated Authorization Policy.
404 Not Found Rendered in multiple scenarios. Most commonly, it is rendered when you try to access or modify an object that does not exist. You can also set an Authorization Policy's http_status to 404 to force render this page instead of the default 403.
500 Server Error If there is an error that cannot be handled gracefully, a server error page is displayed.
503 Maintenance You can enable maintenance mode through the Partner Portal (check the maintenance_mode attribute).

Other formats

Just as any other page, error pages can have various formats responding to different requests.

For example, our documentation page will return an error if a page in the json format does not exist:

You can create any error page to any format supported by Pages.


This text file does not exist. Double-check the URL in the address bar.
<?xml version="1.0" encoding="UTF-8"?>
  <Message>This file does not exist.</Message>

Note: In this case, we did not include slug or format properties in page definition because they are both defined inside the file name, but you can still do it if you prefer to.

Related topics

Contribute to this page

Github Icon


We are always happy to help with any questions you may have.

contact us