LOG IN SIGN UP
Documentation

Creating error pages with custom responses

  Last updated October 23, 2018

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.

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 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.
  5. To create error pages with custom responses for 404 and 503 errors, click the 404 page and 503 page switches.

    404 and 503 error quick config fields

  6. In the HTML response fields, customize the response for the 404 and 503 error pages.
  7. Click the Save buttons to save the responses.
  8. Click the Activate button 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 it to 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 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.
  5. Click the Set up advanced 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're creating (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.

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 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 VCL Snippets link. The VCL Snippets page appears.
  5. Click Create Snippet. The Create a VCL snippet page appears.

    vcl snippet condition

  6. In the Name field, type 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 recv (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 the VCL Snippets link. The VCL Snippets page appears.
  2. Click Create Snippet. The Create a VCL snippet page appears.

    vcl snippet error message

  3. In the Name field, type an appropriate name (e.g., Create Custom Response Synthetic).
  4. From the Type controls, select within subroutine.
  5. From the Select subroutine menu, select recv (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.

  7. Click Create to create the snippet.
  8. Click the Activate button to deploy your configuration changes.

Back to Top