Amazon CloudFront
Developer Guide (API Version 2014-10-21)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Customizing Error Responses

If the objects that you're serving through CloudFront are unavailable for some reason, your web server typically returns an HTTP status code to CloudFront. For example, if a viewer specifies an invalid URL, your web server returns a 404 status code to CloudFront, and CloudFront returns that status code to the viewer. The viewer displays a brief and sparsely formatted default message similar to this:

Not Found: The requested URL /myfilename.html was not found on this server.

If you'd rather display a custom error message, possibly using the same formatting as the rest of your website, you can have CloudFront return to the viewer an object (for example, an HTML file) that contains your custom error message.

AWS 404 page.

You can specify a different object for each supported HTTP status code, or you can use the same object for all of the supported status codes. You can also choose to specify objects for some status codes and not for others.

The objects that you're serving through CloudFront can be unavailable for a variety of reasons. These fall into two broad categories:

  • Client errors indicate a problem with the request. For example, an object with the specified name isn't available, or the user doesn't have the permissions required to get an object in your Amazon S3 bucket. When a client error occurs, the origin returns an HTTP status code in the 400 range to CloudFront.

  • Server errors indicate a problem with the origin server. For example, the HTTP server is busy or unavailable. When a server error occurs, either your origin server returns an HTTP status code in the 500 range to CloudFront, or CloudFront doesn't get a response from your origin server for a certain period of time and assumes a 504 status code (gateway timeout).

The HTTP status codes for which CloudFront can return a custom error page include the following:

  • 400, 403, 404, 405, 414

  • 500, 501, 502, 503, 504

For a detailed explanation of how CloudFront handles error responses from your origin, see How CloudFront Processes and Caches HTTP 4xx and 5xx Status Codes.

Creating or Updating a Cache Behavior for Custom Error Pages

If you want to store your objects and your custom error pages in different locations, your distribution must include a cache behavior for which the following is true:

  • The value of Path Pattern matches the path to your custom error messages. For example, suppose you saved custom error pages for 4xx errors in an Amazon S3 bucket in a directory named /4xx-errors. Your distribution must include a cache behavior for which the path pattern routes requests for your custom error pages to that location, for example, /4xx-errors/*.

  • The value of Origin specifies the value of Origin ID for the origin that contains your custom error pages.

For more information, see Cache Behavior Settings in the topic Values that You Specify When You Create or Update a Web Distribution.

Changing Response Codes

You can choose the HTTP status code CloudFront returns along with a custom error page for a given HTTP status code. For example, if your origin returns a 500 status code to CloudFront, you might want CloudFront to return a custom error page and a 200 status code (OK) to the viewer. There are a variety of reasons that you might want CloudFront to return a status code different from the one that your origin returned:

  • Some Internet devices (some firewalls and corporate proxies, for example) intercept HTTP 4xx and 5xx and prevent the response from being returned to the viewer. If you substitute 200, the response typically won't be intercepted.

  • If you don't care about distinguishing among different client errors or server errors, you can specify 400 or 500 as the value that CloudFront returns for all 4xx or 5xx status codes.

  • You might want to return a 200 status code (OK) and static website so your customers don't know that your website is down.

HTTP status codes that CloudFront can return along with a custom error page include the following:

  • 200

  • 400, 403, 404, 405, 414

  • 500, 501, 502, 503, 504

Controlling How Long CloudFront Caches Errors

By default, when your origin returns an HTTP 4xx or 5xx status code, CloudFront caches these error responses for five minutes and then submits the next request for the object to your origin to see whether the problem that caused the error has been resolved and the requested object is now available.

You can specify the error-caching duration—the Error Caching Minimum TTL—for each 4xx and 5xx status code that CloudFront caches. When you specify a duration, note the following:

  • If you specify a short error-caching duration, CloudFront forwards more requests to your origin than if you specify a longer duration. For 5xx errors, this may aggravate the problem that originally caused your origin to return an error.

  • When your origin returns an error for an object, CloudFront responds to requests for the object either with the error response or with your custom error page until the error-caching duration elapses. If you specify a long error-caching duration, CloudFront might continue to respond to requests with an error response or your custom error page for a long time after the object becomes available again.

If you want to control how long CloudFront caches errors for individual objects, you can configure your origin server to add the applicable header to the error response for that object:

  • If the origin adds a Cache-Control max-age or Cache-Control s-maxage directive, or an Expires header: CloudFront caches error responses for the greater of the value in the header or the value of Error Caching Minimum TTL.

  • If the origin adds other Cache-Control directives or adds no headers: CloudFront caches error responses for the value of Error Caching Minimum TTL.

If the expiration time for a 4xx or 5xx status code for an object is longer than you want to wait, you can invalidate the status code by using the URL of the requested object. If your origin is returning an error response for multiple objects, you need to invalidate each object separately. For more information about invalidating objects, see Invalidating Objects (Web Distributions Only).

How CloudFront Responds When a Custom Error Page Is Unavailable

If you configure CloudFront to return a custom error page for an HTTP status code but the custom error page isn't available, CloudFront returns to the viewer the status code that CloudFront received from the origin that contains the custom error pages. For example, suppose your custom origin returns a 500 status code and you have configured CloudFront to get a custom error page for a 500 status code from an Amazon S3 bucket. However, someone accidentally deleted the custom error page from your bucket. CloudFront will return an HTTP 404 status code (not found) to the viewer that requested the object.

Pricing for Custom Error Pages

When CloudFront returns a custom error page to a viewer, you pay the standard CloudFront charges for the custom error page, not the charges for the requested object. For more information about CloudFront charges, see CloudFront Billing and Usage Reports.

Configuring Error Response Behavior

You can use either the CloudFront API or console to configure CloudFront error responses. For information about using the CloudFront API to configure error responses, go to PUT Distribution Config in the Amazon CloudFront API Reference, and see the CustomErrorResponses element.

To configure CloudFront error responses using the console

  1. Create the custom error pages that you want CloudFront to return to viewers when your origin returns HTTP 4xx or 5xx errors. Save the pages in a location that is accessible to CloudFront.

    We recommend that you store custom error pages in an Amazon S3 bucket even if you're using a custom origin. If you store custom error pages on an HTTP server and the server starts to return 5xx errors, CloudFront can't get the files that you want to return to viewers because the origin server is unavailable.

  2. Confirm that you have granted CloudFront at least read permission to your custom error page objects.

    For more information about Amazon S3 permissions, see Access Control in the Amazon Simple Storage Service Developer Guide. For information on using the Amazon S3 console to update permissions, go to the Amazon Simple Storage Service Console User Guide.

  3. (Optional) Configure your origin server to add Cache-Control directives or an Expires header along with the error response for specific objects, if applicable. For more information, see Controlling How Long CloudFront Caches Errors.

  4. Sign in to the AWS Management Console and open the CloudFront console at https://console.aws.amazon.com/cloudfront/.

  5. In the list of distributions, select the distribution to update and click Distribution Settings.

  6. Click the Error Pages tab. Then either click Create Custom Error Response, or select an existing error code and click Edit.

    Select Web as the distribution type.
  7. Enter the applicable values. For more information, see Custom Error Pages and Error Caching.

  8. If you configured CloudFront to return custom error pages, add or update the applicable cache behaviors. For more information, see Creating or Updating a Cache Behavior for Custom Error Pages.

  9. To save your changes, click Yes, Edit.