How to use custom error pages

Implementation

If during rendering an error occurs, PageBuilder Engine will by default print out the error. While this behavior is useful during site buildout, in production we want to make these errors more user friendly. To facilitate this, PageBuilder Engine automatically looks for pages at the path /error/{statusCode} and if found will serve these in place of the default error message.

Example: 404 Not Found page

We want to have a 404 page that displays a “Sorry Not Found” message. To do this we would create and publish a page from the PageBuilder Editor called /error/404 and add to it our standard features (header, footer, etc) as well as a feature that displays our not found message. Now, when a user comes to a URL that results in a 404 they will see our custom 404 page instead of a default error message.

Example: 410 Gone page

The 410 Gone status code indicates that content previously existed at a URL but has been permanently removed. Unlike a 404, a 410 signals to search engines that the content is intentionally gone and should be de-indexed.

To return 410 responses, you need two things: a content source that throws the 410 status code, and a custom error page to display to visitors.

Create a content source that returns 410

In your content source’s fetch function, throw an error with statusCode set to 410 when the requested path matches content you have removed.

Tip

Use fetch instead of resolve when you need to conditionally throw errors. A resolve function processes default errors automatically, which prevents custom error logic from running. See for details.

const defined410Paths = [
  /^\/old-section(\/.*)?$/,
  /^\/archived-content(\/.*)?$/,
  // add patterns for removed sections, categories, or stories
];

const GoneError = (message = 'Gone') => {
  const err = new Error(message);
  err.statusCode = 410;
  return err;
};

const fetch = ({ requestUri }) => {
  const isGone = defined410Paths.some((pattern) => pattern.test(requestUri));
  if (isGone) {
    throw GoneError(`Content permanently removed: ${requestUri}`);
  }
  // ...normal content fetching logic
};

You can also throw 410 based on an API response instead of maintaining a URL list:

const fetch = async ({ website_url, 'arc-site': site }) => {
  try {
    const { data } = await axios.get(
      `${CONTENT_BASE}/content/v4/?website_url=${website_url}&website=${site}`,
      { headers: { Authorization: `Bearer ${ARC_ACCESS_TOKEN}` } }
    );
    return data;
  } catch (error) {
    if (error.response?.status === 404) {
      // If you know this content was intentionally removed, return 410
      const err = new Error('Content has been permanently removed');
      err.statusCode = 410;
      throw err;
    }
    const err = new Error(error.message);
    err.statusCode = error.response?.status || 500;
    throw err;
  }
};

Caution

Never throw raw error objects from HTTP libraries like Axios. They may contain sensitive data such as access tokens in request headers. Always construct a new, sanitized error. See for best practices.

Create a custom error page for your readers to see

Without a custom error page, visitors see a bare default message (e.g., “Gone” for 410, “Not Found” for 404). To show a branded page for any error status code:

1. Open PageBuilder Editor
2. Create a new page at the path /error/{statusCode} (e.g., /error/410, /error/404, /error/500)
3. Add your standard layout features (header, navigation, footer)
4. Add a feature that displays an appropriate message for that error
5. Publish the page

PageBuilder Engine automatically looks for a page matching the status code and renders it. The HTTP response still returns the correct status code in the header — the custom page only controls what visitors see in the browser.

When to use 410 vs 404

Scenario	Status code
Content never existed at this URL	404
Content was permanently removed	410
Section or category shut down	410
Temporary maintenance or unpublish	404
Content migrated to a new URL	301

Common status codes

Here are some common status codes that PageBuilder Engine can serve which you may want custom error pages for. This list is not exhaustive — the same approach outlined above applies for any status code.

Status Code	Meaning
404	Not Found
410	Gone
500	Internal Server Error