Creating error pages with custom responses

  Last updated May 23, 2017

The default error responses served by Fastly can be jarring for your users, especially when using Fastly for consumer applications. This tutorial shows you how to set up your service configuration to serve a custom page or a synthetic response when we receive an error code from your backend.

We assume you are already accustomed to editing and deploying configurations using the web interface. If you are not familiar with the web interface, see our basic setup and configuration information to learn more before you continue.


In this tutorial, we will create a response object that contains the HTML you want to serve for your error page. We provide example HTML, but you can use any HTML you see fit. The response object will require that you use a condition in order for it to be served. If you are not familiar with conditions or responses we suggest you read the following:

Creating the custom response

  1. Log in to the Fastly web interface and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the Configuration button and then select Clone active. The Domains page appears.
  4. Click the Content link. The Content page appears.

    the Content page

  5. Click the Create response button. The Create a synthetic response page appears.

    the Create a synthetic response page

  6. Fill out the Create a synthetic response fields as follows:
    • In the Name field, type a name for the response you're creating (e.g., Custom 404).
    • From the Status menu, select the appropriate status (e.g., 404 Not Found).
    • In the MIME Type field, specify the Content-Type of the response (e.g., text/html).
    • In the Response field, type the content to be served when delivering a response.
  7. Click the Create button. Your new response appears in the list of responses.
  8. Click the Attach a condition link to the right of the name of your new response. The Create a new condition window appears.

    the New Condition window

  9. Fill out the Create a new condition fields as follows:
    • From the Type menu, select the type of condition you want (e.g., Cache).
    • In the Name field, type a name for the condition you're creating (e.g., 404 Not Found).
    • In the Apply if field, type the condition under which the new response occurs in the following format:

      beresp.status == ###

    where ### equals the status condition you're creating the response for. For example, using the value of beresp.status == 404 in the Apply if field here tells Fastly to use this response object whenever origin servers return a 404 status. (See the Conditions guides for more detailed information on conditions.)

  10. Click the Save and apply to button. The condition is created and applied to the custom response object you made earlier.
  11. Click the Activate button to deploy your configuration changes. Fastly will now serve your custom HTML error page when required.

Back to Top