API Gateway HTTP 504 상태 코드 시간 제한 오류를 해결하려면 어떻게 해야 합니까?

간략한 설명

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

API Gateway의 504 시간 제한 오류를 해결하려면 먼저 Amazon CloudWatch 이벤트 로그에서 오류의 원인을 찾아서 확인합니다. 그리고 다음 방법 중 하나를 사용하여 제한 시간이 초과되지 않을 때까지 통합 요청의 런타임을 낮춥니다.

또한 리전 및 프라이빗 REST API의 통합 시간 제한을 기본 제한인 29초보다 훨씬 더 늘릴 수 있습니다.

해결 방법

CloudWatch Logs에서 504 오류의 원인 식별 및 확인

다음 단계를 완료합니다.

1. Rest API 및 Websocket API의 경우, 504 오류에 대해 API Gateway 로깅을 설정합니다. HTTP API의 경우, CloudWatch 로그에 로그를 작성하는 로깅을 활성화합니다.

2. API에서 504 오류를 수동으로 재현합니다.

3. API에 대한 액세스 로깅을 활성화합니다. 이후 다음 파라미터 자리 표시자를 사용하여 오류의 원인을 진단합니다.

   $context.integration.status: The status code returned from an integration. For AWS Lambda proxy integrations, this is the status code that your Lambda function code returns.$context.integrationStatus: For Lambda proxy integration, this parameter represents the status code returned from Lambda, not from the backend Lambda function.
   $context.integrationLatency: The integration latency in ms.

   자세한 내용은 데이터 변환을 위한 컨텍스트 변수를 참조하십시오.

4. 액세스 로그에서 '5##' 상태 코드를 필터링하려면 다음 CloudWatch Log Insights 쿼리를 사용합니다.

   fields @timestamp, @message, @logStream| filter status like '5'
   | sort @timestamp desc
   | display @timestamp,httpMethod,resourcePath,status,extendedRequestId,requestId

5. CloudWatch 콘솔에서 오류를 수신한 통합에 대한 API Gateway 로그 이벤트를 확인합니다.

6. CloudWatch 로그에서 요청 ID를 추적합니다. 통합에 시간 제한이 있는 경우, Endpoint request body after transformations: 행 다음에 “Execution failed due to a timeout” 오류가 표시됩니다. 자세한 내용은 내 CloudWatch Logs에서 API Gateway REST API 오류를 찾으려면 어떻게 해야 합니까?를 참조하십시오.

7. 오류를 필터링하고 API Gateway 실행 로그 그룹을 선택하려면 다음 CloudWatch 로그 인사이트 쿼리를 사용합니다.

   fields @timestamp, @message|filter @message like "Execution failed due to a timeout error"
   |sort @timestamp desc

8. 오류의 원인을 확인하려면 백엔드 로그를 검토하고 연결된 통합 엔드포인트가 호출되었는지 확인합니다.

9. 통합이 요청 처리를 완료하고 API Gateway에 응답하는 데 걸린 시간을 확인합니다.

10. 통합이 호출되지 않은 경우 클라이언트에서 API 재시도를 구현합니다. API Gateway 서비스의 일시적인 네트워크 장애로 인해 오류가 발생할 수 있습니다.
    참고: API 요청을 재시도할 때 데이터 충돌을 방지할 수 있도록 애플리케이션이 멱등성이어야 합니다.

통합이 호출되었지만 여전히 504 오류 메시지가 반환되는 경우에는 통합의 런타임을 줄이십시오.

통합 런타임 줄이기

다음 작업을 완료하십시오.

• API Gateway가 클라이언트로 HTTP 응답을 보내는 데 필요한 로직만 백엔드 통합에 포함되어 있는지 확인하십시오.
• 비종속 또는 후처리 로직을 AWS Lambda와 같은 다른 서비스로 이동하십시오.
• 네트워크 지연으로 인해 504 오류가 발생하는 경우 클라이언트 측 애플리케이션에서 재시도 로직을 구현하십시오.
• AWS 제품 및 서비스의 모범 사례를 따라 백엔드 통합 성능을 개선하십시오.
• 백엔드 Lambda 함수의 비동기 호출을 설정하십시오.

리전 및 프라이빗 API의 통합 시간 제한 늘리기

할당량 요청을 제출하여 리전 API 및 프라이빗 API의 기본 통합 시간 제한 할당량을 29초 이상으로 늘릴 수 있습니다. 하지만 통합 시간 초과를 늘리려면 AWS 계정의 리전 수준 스로틀 할당량을 줄여야 할 수 있습니다.

참고: 통합 시간 제한을 늘리는 경우 기본 시간 제한 값인 29초를 새 값으로 변경해야 합니다. 예를 들어 증가를 적용하려는 통합에서 기본 시간 제한 값인 29초를 변경하십시오. 그런 다음 API를 재배포하여 새 통합 시간제한을 적용합니다.

관련 정보

API Gateway의 REST API 통합

API Gateway에서 WebSocket API 통합 요청 설정

API Gateway에서 HTTP API 통합 만들기

Lambda 백엔드를 사용하여 API Gateway REST API의 HTTP 504 오류를 해결하려면 어떻게 해야 합니까?