How do I troubleshoot CloudFront "503 Service Unavailable" errors?

Resolution

To resolve an HTTP 503 status code (Service Unavailable), take the following actions for your error.

HTTP 503 errors for your origin server

If there are performance issues on the origin server or the server is unavailable, then you might receive the "503 Service Unavailable" error.

To troubleshoot this issue, see Origin server does not have enough capacity to support the request rate.

HTTP 503 errors with Lambda@Edge or the CloudFront function

If there are unhandled exceptions in the AWS Lambda function or errors in the code, then you might receive the "503 Service Unavailable" error.

To fix your code, add logging statements to the Lambda functions. Review your Lambda@Edge logs and CloudFront Functions logs to verify that CloudFront works correctly. For more information, see Troubleshoot invocation issues in Lambda and Troubleshoot execution issues in Lambda.

If you exceed a Lambda@Edge quota, then Lambda blocks the Lambda function execution and CloudFront returns an HTTP 503 error. To resolve an HTTP 503 error from exceeded quotas, see How do I troubleshoot 502 and 503 errors caused by Lambda@Edge functions in CloudFront?

HTTP 503 errors with Amazon S3

If you have integrated applications or your origins are with Amazon Simple Storage Service (Amazon S3), then you might receive an HTTP 500 or 503 error. To resolve these errors, see How do I troubleshoot a HTTP 500 or 503 error from Amazon S3?

Prevent CloudFront from caching HTTP 503 errors

CloudFront forwards error responses from the origin to the client by default. CloudFront caches the origin's error response for 10 seconds.

If the origin's error response contains a Cache-Control header, then CloudFront caches the error with the relevant time to live (TTL) instead of the default 10 seconds. CloudFront doesn't cache its own error responses, unless specified otherwise in a custom error response. You can create a custom error response for HTTP 503 errors with a TTL of 0 seconds to prevent CloudFront from caching the error.

To optimize cache efficiency, use the CachingOptimized policy. This policy sets a lower minimum TTL of 1 second for error responses instead of the default value of 10 seconds. For more information, see Use managed cache policies.

It's a best practice to build retry logic into your applications to retry requests that return an HTTP 503 error. All AWS SDKs have a built-in retry mechanism with an algorithm that uses exponential backoff. This algorithm implements increasingly longer wait times between retries for consecutive error responses. Many exponential backoff algorithms use jitter (randomized delay) to prevent successive collisions. For more information, see Retry behavior.