Customize error response pages

When a request to the Fastly origin fails, Fastly returns default response pages with basic formatting and generic messaging that can be confusing for users. For example, Fastly returns the following default error page when an origin request fails with a 503.

Fastly default error page

You can update your store configuration to replace some default response pages with pages that have friendlier messaging and improved HTML styling as shown in the following example.

Fastly custom error page

Currently, you can customize the following Fastly response pages for your Magento Commerce Cloud project through the Magento Admin UI.

HTML coding requirements

The HTML code for the custom page must meet the following requirements:

  • Content can contain up to 65,535 characters.
  • Specify all CSS inline in the HTML source.
  • Bundle images in the HTML page using base64 so that they display even if Fastly is offline. See Data URIs on the css-tricks site.

Customize the 503 response page

Customers see the default 503 response page in the following cases:

  • When a request to the Fastly origin returns a response status great than 500.
  • When the Fastly origin is down, for example due to a timeout, maintenance activity, or health issues.

You can customize the default page by adapting the following HTML code to include styling to match your Magento Commerce store theme and modifying the title and messaging as needed.

<!DOCTYPE html>
<html>
   <head>
      <meta charset="UTF-8">
         <title>503</title>
   </head>
   <body>
      <p>Service unavailable</p>
   </body></html>

Verify that the modified source displays correctly in the browser. Then, add the customized HTML code to the Fastly configuration.

To add the custom response page to the Fastly configuration:

  1. Log in to the Magento Admin UI.

  2. Click Stores > Settings > Configuration > Advanced > System.

  3. In the right pane, expand Full Page Cache > Fastly Configuration > Custom Synthetic Pages.

    Edit 503 error page

  4. Click Set HTML.

  5. Copy and paste the source code for your custom response page into the HTML field.

    Update 503 response

  6. Click Upload at the top of the page to upload the customized HTML source to the Fastly server.

  7. Click Save Config at the top of the page to save the updated configuration file.

One or more of the Cache Types are invalidated: Configuration, Page Cache. Please go to Cache Management and refresh cache types.

Customize the WAF response page

If the Magento Managed Cloud WAF blocks a customer request at the Fastly origin, they see the following default response page:

WAF error response page

The following code sample shows the HTML source for the default page:

<html>
  <head>
    <title>Magento 403 Forbidden</title>
  </head>
  <body>
    <p>The requested URL was rejected.</p>
    <p>For additional information, please contact support and provide this reference ID:</p>
    <p>"} req.http.x-request-id {"</p>
    <p><button onclick='history.back();'>Go Back</button></p>
  </body>
</html>

You can use the Custom Synthetic Pages > Edit WAF page option in the Fastly configuration menu to customize the default code for your Magento Commerce Cloud project. When you edit the code, retain the following line that provides the reference ID for the WAF blocking event:

<p>"} req.http.x-request-id {"</p>

The Edit WAF option is available only if the Managed Cloud WAF service is enabled for your project.

To edit the WAF page:

  1. Log in to the Magento Admin UI.

  2. Click Stores > Settings > Configuration > Advanced > System.

  3. In the right pane, expand Full Page Cache > Fastly Configuration > Custom Synthetic Pages.

    Edit WAF response option

  4. Click Edit WAF page.

  5. Complete the fields to update the HTML.

    Update WAF response page

    • Status—Select the 403 Forbidden status.
    • MIME type—Type text/html.
    • Content—Edit the default HTML response to add custom CSS and update the title and messaging as needed.
  6. Click Upload at the top of the page to upload the customized HTML source to the Fastly server.

  7. Click Save Config at the top of the page to save the updated configuration file.