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

간략한 설명

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

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

해결 방법

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.

   자세한 내용은 데이터 모델, 권한 부여자, 매핑 템플릿 및 CloudWatch 액세스 로깅에 대한 $context 변수 섹션을 참조하세요.

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

   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 오류 메시지가 반환되는 경우 통합의 런타임을 줄여보십시오. HTTP API인 경우, 최대 통합 요청 시간 제한 파라미터를 늘려 보십시오. 자세한 내용은 Amazon API Gateway 통합 시간 제한이 29초를 초과하여 증가를 참조하십시오.

참고: API Gateway REST API의 기본 최대 통합 시간 제한은 29초입니다. HTTP API의 경우 최대 30초까지 시간 제한을 구성할 수 있습니다.

통합 런타임 줄이기

다음 작업 중 하나 이상을 수행합니다.

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

관련 정보

API Gateway의 REST API 통합

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

API Gateway에서 HTTP API 통합 생성

Amazon API Gateway 할당량 및 중요 정보