API Gateway HTTP 504 ステータスコードのタイムアウトエラーをトラブルシューティングする方法を教えてください。

簡単な説明

統合リクエストが設定済みの API Gateway API の最大統合タイムアウトパラメータよりも長くかかる場合、API Gateway は HTTP 504 ステータスコードを返します。

API Gateway からの 504 タイムアウトエラーをトラブルシューティングするには、まず Amazon CloudWatch イベントログでエラーの原因を特定して検証します。次に、次の方法のいずれかを使用して、タイムアウトが発生しないように統合リクエストのランタイムを短縮します。

リージョン REST API とプライベート REST API の統合タイムアウト制限を、デフォルトの制限である 29 秒から引き上げることもできます。

解決策

CloudWatch ログの 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 Logs でリクエスト ID を追跡します。統合でタイムアウトが発生している場合、**変換後のエンドポイントリクエスト本文:**行の後に「タイムアウトにより実行が失敗しました」というエラーが表示されます。詳細については、「CloudWatch Logs で API Gateway REST API エラーを見つけるにはどうすればよいですか?」を参照してください。

7. エラーをフィルター処理し、API Gateway 実行ロググループを選択するには、次の CloudWatch Log Insights クエリを使用します。

   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 とプライベート 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 エラーのトラブルシューティング方法を教えてください。