Amazon Simple Storage Service
Developer Guide (API Version 2006-03-01)

Custom Error Document Support

The following table lists the subset of HTTP response codes that Amazon S3 returns when an error occurs.

HTTP Error Code Description
301 Moved Permanently When a user sends a request directly to the Amazon S3 website endpoints (http://s3-website-<region>, Amazon S3 returns a 301 Moved Permanently response and redirects those requests to
302 Found

When Amazon S3 receives a request for a key x, http://<bucket>.s3-website-<region>, without a trailing slash, it first looks for the object with the keyname x. If the object is not found, Amazon S3 determines that the request is for subfolder x and redirects the request by adding a slash at the end, and returns 302 Found.

304 Not Modified

Amazon S3 users request headers If-Modified-Since, If-Unmodified-Since, If-Match and/or If-None-Match to determine whether the requested object is same as the cached copy held by the client. If the object is the same, the website endpoint returns a 304 Not Modified response.

400 Malformed Request

The website endpoint responds with a 400 Malformed Request when a user attempts to access a bucket through the incorrect regional endpoint.

403 Forbidden

The website endpoint responds with a 403 Forbidden when a user request translates to an object that is not publicly readable. The object owner must make the object publicly readable using a bucket policy or an ACL.

404 Not Found

The website endpoint responds with 404 Not Found for the following reasons:

  • Amazon S3 determines the website URL refers to an object key that does not exist

  • Amazon infers the request is for an index document that does not exist

  • A bucket specified in the URL does not exist

  • A bucket specified in the URL exists, however, it is not configured as a website

You can create a custom document that is returned for 404 Not Found. Make sure the document is uploaded to the bucket configured as a website, and that the website hosting configuration is set to use the document.

For information on how Amazon S3 interprets the URL as a request for an object or an index document, see Index Document Support .

500 Service Error

The website endpoint responds with a 500 Service Error when an internal server error occurs.

503 Service Unavailable

The website endpoint responds with a 503 Service Unavailable when Amazon S3 determines that you need to reduce your request rate.

For each of these errors, Amazon S3 returns a predefined HTML as shown in the following sample HTML returned for 403 Forbidden response.

You can optionally provide a custom error document with a user-friendly error message and with additional help. You provide this custom error document as part of adding website configuration to your bucket. Amazon S3 returns your custom error document for only the HTTP 4XX class of error codes.

Error Documents and Browser Behavior

When an error occurs, Amazon S3 returns an HTML error document. If you have configured your website with a custom error document, Amazon S3 returns that error document. However, note that when an error occurs, some browsers display their own error message, ignoring the error document Amazon S3 returns. For example, when an HTTP 404 Not Found error occurs, Chrome might display its own error ignoring the error document that Amazon S3 returns.