API Gateway의 5xx 오류를 해결하려면 어떻게 해야 하나요?

4분 분량

Amazon API Gateway API를 호출하면 5xx 오류가 발생합니다.

간략한 설명

HTTP 5xx 응답 코드는 서버 오류를 나타냅니다. API Gateway 5xx 오류에는 다음과 같은 경우가 포함됩니다.

500 내부 서버
502 잘못된 게이트웨이
503 서비스를 사용할 수 없음
504 엔드포인트 요청 시간이 초과됨

해결 방법

시작하기 전에 단계에 따라 Amazon CloudWatch Logs를 켜서 API Gateway 오류를 해결하세요.

CloudWatch 로그를 사용하여 API Gateway에서 5xx 오류를 찾을 수 있습니다. API Gateway 메트릭 5XXError는 일정한 기간 동안 캡처된 서버 측 오류의 수를 계산합니다.

**참고:**AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하는 경우 최신 AWS CLI 버전을 사용하고 있는지 확인하세요.

500 오류: 내부 서버 오류

이 오류는 다음과 같은 시나리오로 인해 발생할 수 있습니다.

AWS Lambda 함수 코드의 오류
단계 변수를 사용할 권한 누락
잘못되거나 누락된 HTTP 상태 코드 매핑
제한 문제
POST의 정의되지 않은 HTTP 메서드
Lambda 사용 권한
Lambda 함수 JSON 형식 문제
10MB를 초과하는 백엔드 페이로드 크기
프라이빗 엔드포인트 통합
내부 서비스 장애

Lambda 함수 코드의 오류

Lambda와 통합되는 API 엔드포인트 500 오류는 Lambda 함수의 코드에 오류가 있음을 나타낼 수 있습니다. 자세한 내용 및 문제 해결 방법은 Amazon API Gateway 및 AWS Lambda의 오류 처리 패턴을 참조하세요.

단계 변수를 사용할 권한 누락

단계 변수를 사용하여 Lambda 함수를 호출하도록 API Gateway를 설정하는 경우, 내부 서버 오류가 발생할 수 있습니다. 이 오류를 해결하려면 단계 변수를 사용하여 API Gateway에서 Lambda 통합을 정의했습니다. API 메서드를 호출할 때 “내부 서버 오류”와 500 상태 코드가 나타나는 이유는 무엇인가요?를 참조하세요.

잘못되거나 누락된 HTTP 상태 코드 매핑

HTTP 상태 코드 매핑이 잘못되거나 누락되면 500 오류가 발생할 수도 있습니다. 이 문제를 해결하려면 API Gateway에서 모의 통합을 설정합니다.

제한 문제

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

POST의 정의되지 않은 HTTP 메서드

Lambda 통합의 경우 통합 요청에 POST의 HTTP 메서드를 사용해야 합니다.

AWS CLI 명령 put-integration을 실행하여 메서드 통합 요청을 업데이트합니다.

aws apigateway put-integration \
    --rest-api-id id \
    --resource-id id \
    --http-method ANY \
    --type AWS_PROXY \
    --integration-http-method POST \
    --uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations

그런 다음, AWS CLI 명령 create-deployment를 사용하여 REST API를 배포합니다.

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name <value>

Lambda 사용 권한

통합된 Lambda 함수 또는 Lambda 권한 부여자의 리소스 기반 정책에 API에 대한 함수 호출 권한이 포함되어 있는지 확인하세요. 지침에 따라 Lambda 함수의 리소스 기반 정책을 업데이트합니다.

Lambda 함수 JSON 형식 문제

통합된 Lambda 함수는 REST API 및 HTTP API에 대해 미리 정의된 JSON 형식에 따라 출력을 반환하지 않습니다. Lambda 함수 또는 Lambda 권한 부여자를 JSON 형식으로 업데이트합니다.

REST API:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

HTTP API:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

10MB를 초과하는 백엔드 페이로드 크기

최대 백엔드 페이로드 크기는 10MB입니다. 크기를 늘릴 수 없습니다. 백엔드 페이로드 크기가 10MB 기본 할당량을 초과하지 않아야 합니다.

프라이빗 엔드포인트 통합

프라이빗 API 엔드포인트를 사용하는 경우 API Gateway 프라이빗 통합도 구성해야 합니다. 지침에 따라 API Gateway 프라이빗 통합을 설정합니다.

내부 서비스 장애

AWS에 내부 서비스 문제가 발생하면 500 오류가 발생할 수 있습니다. AWS 또는 API Gateway 서비스 내에서 문제가 해결될 때까지 기다린 다음, 지수 백오프를 사용하여 요청을 다시 시도합니다.

502 오류: 잘못된 게이트웨이

502 오류 코드는 API Gateway가 통합하는 AWS 서비스(예: AWS Lambda 함수)와 관련이 있습니다. API Gateway는 응답을 게이트웨이 또는 프록시로 처리할 수 없습니다.

이 문제를 해결하려면 Lambda 프록시 통합으로 API Gateway REST API의 HTTP 502 오류를 해결하려면 어떻게 해야 하나요?를 참조하세요.

**참고:**API Gateway는 백엔드 서비스 응답을 해석할 때 매핑 템플릿을 사용하여 통합 응답 섹션의 형식을 매핑합니다. 자세한 내용은 API Gateway에서 통합 응답 설정을 참조하세요.

503 오류: 서비스를 사용할 수 없음

503 오류 코드는 백엔드 통합과 관련이 있으며 API Gateway API가 응답을 받을 수 없는 경우입니다.

이 오류는 다음 시나리오에서 발생할 수 있습니다.

백엔드 서버가 용량을 초과하여 과부하되어 새 클라이언트 요청을 처리할 수 없습니다.
백엔드 서버가 임시 유지 보수 중입니다.

이 오류를 해결하려면 백엔드 서버에 더 많은 리소스를 프로비전하고 클라이언트에서 지수 백오프 및 재시도 메커니즘을 활성화하는 것이 좋습니다. 그 후 요청을 다시 시도합니다.

504 오류: 엔드포인트 요청 시간이 초과됨

통합 요청이 API Gateway REST API의 최대 통합 시간 제한 파라미터보다 오래 걸리면 API Gateway가 HTTP 504 상태 코드를 반환합니다.

이 오류를 해결하려면 API Gateway의 API HTTP 504 제한 시간 오류를 해결하려면 어떻게 해야 하나요?를 참조하세요.