Configure a Custom Error Page

Overview

You can configure a custom HTML error page to display when your site is unavailable due to issues such as misconfiguration or failed distribution deployment. This error page can include project-specific information, such as contact details or links to alternate sites.

When to Use

Configure a custom error page to provide users with clear information and guidance when your site returns a 503 error during deployment or configuration failures.

Prerequisites

Access to Mission Control
API credentials for your Bloomreach Cloud stack
A prepared errorpage.html file with your custom content

Implementation Steps

Custom error page configuration requires two steps:

Upload the custom error page file
Associate the uploaded file with the 503 error code

1. Upload the Custom Error Page

You can upload your errorpage.html file using either Mission Control or the API.

To upload via Mission Control:

Go to Files > Configurations (switch to the Configurations tab)
Select Upload configuration file
Upload your errorpage.html file

To upload via API:

Refer to the Mission Control documentation for details on uploading configuration files through the API.

2. Associate the File with the 503 Error Code

You must use the API to link the uploaded file to the 503 error code.

Replace {stack_name} with your stack name and use the fileId of your uploaded file:

curl -X POST \
  https://api.{stack_name}.bloomreach.cloud/v3/customerrorpages/503 \
  -H 'authorization: Bearer eyJhXYZg' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "fileId": "aaaaad-1111-111a-a1aa-aaaaaaaaaa"
}'

Find the `fileId` of the Uploaded File

To retrieve the fileId for your uploaded errorpage.html, use the following API call:

curl -X GET \
  https://api.{stack_name}.bloomreach.cloud/v3/appconfigfiles \
  -H 'authorization: Bearer eyJhXYZg' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json; charset=utf-8'

Verification

After completing these steps, trigger a 503 error (for example, by simulating a deployment failure) and confirm that your custom error page is displayed.

Troubleshooting

If the custom error page does not appear, verify that the fileId is correct and that the file is properly uploaded.
Ensure that the API call to associate the error page with the 503 code returns a successful response.
Confirm that your browser is not caching an old error page.

Use Mission Control