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

최종 업데이트 날짜: 2022년 9월 22일

Amazon API Gateway API를 호출하면 5xx 오류가 발생합니다. API Gateway 5xx 오류를 해결하려면 어떻게 해야 합니까?

간략한 설명

HTTP 5xx 응답 코드는 서버 오류를 나타냅니다. API Gateway 5xx 오류는 다음을 포함합니다.

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

해결 방법

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

API Gateway에서 5xx 오류를 찾기 위해 Amazon CloudWatch Logs를 사용할 수 있습니다. API Gateway metric 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의 오류 처리 패턴을 참조하세요.

스테이지 변수 사용 권한 누락

스테이지 변수를 사용하여 AWS Lambda 함수를 호출하도록 API Gateway를 설정한 경우 '내부 서버 오류'가 표시될 수 있습니다. 이 오류를 해결하려면 API 메서드를 호출할 때 '내부 서버 오류'와 상태 오류 500이 발생하는 이유는 무엇입니까?를 참조하세요.

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

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

제한 문제

요청 수가 많아 백엔드 서비스가 제한되는 경우 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 권한 부여자 함수 JASON 형식을 다음과 유사하게 업데이트하세요.

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 프라이빗 통합을 설정하세요.

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

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

Lambda 프록시 함수와 통합 시 502 오류를 해결하려면 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 시간 초과 오류를 해결하려면 어떻게 해야 하나요?를 참조하십시오.


이 문서가 도움이 되었나요?


결제 또는 기술 지원이 필요하세요?