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. To mitigate this, consider configuring your service to present them with a custom page or a synthetic response when Fastly receives an error code from your origin.

Fastly offers two quick configuration options for creating 404 and 503 error pages directly in the web interface, but you can also use the interface to create error pages for other status codes. If you're working with large blocks of content when styling your error pages, consider creating custom responses using VCL snippets instead.

Creating error pages for 404 and 503 errors

To create error pages with custom responses for 404 and 503 errors, follow the steps below:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. Click Content.

5. To create error pages with custom responses for 404 and 503 errors, click the 404 page and 503 page switches.

   

6. In the HTML response fields, customize the response for the 404 and 503 error pages.

7. Click Save to save the responses.

8. Click Activate to deploy your configuration changes.

Creating error pages for other status codes

You can also create error pages for other HTTP status codes. 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 a custom error page to be served, otherwise a generic error page will be served.

To create and configure an error page for an HTTP status code other than 404 or 503, follow the steps below to create the custom response and the condition under which it should be applied using the web interface:

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.
4. Click Content.

5. Click Set up advanced response.

   

6. Fill out the Create a synthetic response fields as follows:

   • In the Name field, enter 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, enter the content to be served when delivering a response.

7. Click Create.

8. Click the Attach a condition link to the right of the name of your new response.

   

9. Fill out the Create a new condition fields as follows:

   • From the Type menu, select the type of condition you're creating (e.g., Cache).

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

   • In the Apply if field, enter 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 Save and apply to.

11. Click Activate to deploy your configuration changes. Fastly will now serve your custom HTML error page when required.

Creating custom responses using VCL Snippets

To create the custom response using VCL Snippets, create two separate snippets: one to trigger the condition for an internal Fastly error and the second to create the response to that error.

Create a VCL Snippet for a condition

1. Log in to the Fastly web interface.
2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.
3. Click Edit configuration and then select the option to clone the active version.

4. Click VCL Snippets.

5. Click Create Snippet.

   

6. In the Name field, enter an appropriate name (e.g., Catch Error for Custom Response).

7. From the Type controls, select within subroutine.

8. From the Select subroutine menu, select fetch (vcl_fetch).

9. In the VCL field, add the following condition:

   1
   2
   3

   if (beresp.status == ###) {
     error 600 "### Custom Response"
   }

   where ### is the status condition you're creating the response for. The error code used here, 600, is a random number that doesn't conflict with standard HTTP error codes. Consider using custom error code numbers in the 600’s or 700’s to avoid confusion.

10. Click Create to create the snippet.

Create a VCL Snippet for a synthetic response

1. Click VCL Snippets.

2. Click Create Snippet.

   

3. In the Name field, enter an appropriate name (e.g., Create Custom Response Synthetic).

4. From the Type controls, select within subroutine.

5. From the Select subroutine menu, select error (vcl_error).

6. In the VCL field, add the following condition:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14

   if (obj.status == 600) {
     set obj.status = 404;
     set obj.response = "Not Found";
     synthetic {"
       <html>
         <head>
         </head>
         <body>
           <h1>Custom Response</h1>
         </body>
       </html>
     "};
     return(deliver);
   }

   replacing Custom Response with your custom, synthetic response. This VCL tells Fastly to respond with your custom response if a request for an object meets the condition you created in vcl_fetch.

   NOTE

   Synthetic responses don't have a character limit, but including them in the custom VCL file may push that file over its size limit.

7. Click Create to create the snippet.

8. Click Activate to deploy your configuration changes.