Creating error pages with custom responses

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-based configuration application. If you are not familiar with basic editing using the app, please 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 application and click the configure tab (wrench icon).

    the configure tab

  2. From the Service menu, select the appropriate service and then click the blue Configure button. The main controls for your selected service appear.

  3. Click Content from the section list on the left.

  4. In the Responses area at the bottom of the page click the New button. The New Response window appears.

    the New Response window

  5. Fill out the New Response controls as follows:

    • In the Name field, give the response you're creating a name (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).
  6. Click the Create button to create your custom response. Your new response appears in the list of responses.

  7. Click the gear icon to the right of the name of your new response and select Cache Conditions from the menu that appears.

    the Cache Conditions menu selection

    The New Condition window appears (if you have previously created a cache condition, click the new button at the top of the edit condition modal that appears).

  8. In the Name field, give the condition you're creating a name (e.g., 404 Not Found).

  9. In the Apply If field, type the condition under which the new response occurs. The condition should take the following format:

    beresp.status == ###

    where ### equals the status condition you're creating the response for. For instance, using our 404 error example above, your New Condition window would look like this:

    the New Condition window

    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. (Remember: The Conditions guides have more detailed information on conditions.)

  10. Click the Create button and the condition will be created and applied to the custom response object you made earlier.

  11. Deploy your service. Fastly will now serve your custom HTML error page when required.

Back to Top