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.
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 from Your Origin.
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
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.
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 to the viewer that is different from the one that your origin returned to CloudFront:
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
If you enable CloudFront access logs and you configure CloudFront to change the HTTP status code in the response, the value of the
in access logs will contain the status code that you specify. However, the value of the
x-edge-result-type column will not be affected;
it will still contain the result type of the response from the origin. For example, suppose you configure CloudFront to return a status code of
to the viewer when the origin returns
404 (Not Found) to CloudFront. When the origin responds to a request with a
404 status code,
the value in the
sc-status column in the access log will be
200, but the value in the
You can configure CloudFront to return any of the following HTTP status codes along with a custom error page:
400, 403, 404, 405, 414
500, 501, 502, 503, 504
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).
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.
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 Reports.
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
To configure CloudFront error responses using the console
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.
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.
(Optional) Configure your origin server to add
Cache-Control directives or an
along with the error response for specific objects, if applicable. For more information, see
Controlling How Long CloudFront Caches Errors.
Sign in to the AWS Management Console and open the CloudFront console at https://console.aws.amazon.com/cloudfront/.
In the list of distributions, select the distribution to update and choose Distribution Settings.
Choose the Error Pages tab. Then either choose Create Custom Error Response, or choose an existing error code and choose Edit.
Enter the applicable values. For more information, see Custom Error Pages and Error Caching.
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.
To save your changes, choose Yes, Edit.