Lambda와 통합되는 API Gateway 엔드포인트의 상태 코드 500이 포함된 “내부 서버” 오류를 해결하려면 어떻게 해야 합니까?

2분 분량

AWS Lambda와 통합되는 Amazon API Gateway API 엔드포인트(예: /lambda-resource GET)에 HTTP 요청을 보냈습니다. 다음 오류와 함께 상태 코드 500 응답을 받았습니다. {"message": "Internal server error"} 이 오류를 해결하려면 어떻게 해야 합니까?

간략한 설명

이 오류는 다음과 같은 이유 때문일 수 있습니다.

Lambda 함수 권한
제한 문제
HTTP 상태 코드 매핑이 잘못되었거나 누락됨
처리되지 않은 오류

해결 방법

시작하기 전에 단계에 따라 API Gateway 오류 문제 해결을 위해 Amazon CloudWatch Logs를 활성화합니다.

참고:[로그 수준(Log level)]에서 [INFO]를 선택하여 모든 요청에 대한 실행 로그를 생성합니다.

Lambda 함수 권한

API Gateway에 Lambda 함수를 호출할 권한이 없는 경우 “Lambda 함수에 대한 잘못된 권한” 오류가 발생합니다. 이 문제를 해결하려면 API Gateway REST API에서 'Invalid permissions on Lambda function' 오류를 해결하려면 어떻게 해야 하나요?를 참조하세요.

참고: AWS CloudFormation과 같은 다른 서비스를 사용하여 API Gateway 리소스를 배포한 경우 AWS::Lambda::Permission 리소스에 대한 권한이 있는지 확인합니다.

제한 문제

요청 수가 많아 백엔드 서비스가 제한되는 경우 API Gateway API에서 '내부 서버 오류'를 반환할 수 있습니다. 지수 백오프 및 재시도 메커니즘을 활성화하고 요청을 다시 시도할 수 있습니다. 문제가 지속되면 API Gateway 할당량 한도를 확인합니다. 서비스 할당량 한도를 초과한 경우 할당량 증가 요청을 할 수 있습니다.

또한 Lambda 함수 제한 문제로 인해 “Rate exceeded” 및 429개의 “TooManyRequestsException” 오류가 발생할 수 있습니다. 자세한 내용은 "Rate exceeded" 및 429 "TooManyRequestsException" 오류와 함께 Lambda 함수가 제한되는 문제를 해결하려면 어떻게 해야 합니까?를 참조하세요.

함수가 제한되지 않도록 Lambda 함수의 동시성 한도를 늘리도록 요청할 수도 있습니다. 지침은 Lambda 함수에 대한 동시성 한도 증가를 요청하려면 어떻게 해야 합니까?를 참조하세요.

HTTP 상태 코드 매핑이 잘못되었거나 누락됨

HTTP 상태 코드 매핑이 잘못되거나 누락되었을 때도 다음과 유사한 500 오류가 발생할 수 있습니다.

“구성 오류로 인한 실행 실패: 출력 매핑은 잘못된 메서드 응답(2xx/4xx/5xx)을 나타냅니다.”

이 오류를 해결하려면 백엔드에서 반환된 상태 코드에 대한 API 메서드 응답이 존재하고 올바르게 매핑되었는지 확인합니다.

처리되지 않은 오류

Lambda에서 처리되지 않은 오류는 함수 코드의 오류로 인해 함수 제한 시간이 초과되었음을 나타냅니다. 이 오류를 방지하려면 Lambda 함수 코드가 idempotent인지 확인합니다.

디버깅 도구인 AWS X-Ray를 사용하여 함수 코드의 각 섹션을 완료하는 데 걸리는 시간에 대한 세부 정보를 얻을 수도 있습니다.

자세한 내용은 Amazon API Gateway 및 AWS Lambda의 오류 처리 패턴을 참조하세요.