API Gateway の 5xx エラーをトラブルシューティングする方法を教えてください。

所要時間2分

Amazon API Gateway API を呼び出すと、5xx エラーが表示されます。

簡単な説明

HTTP 5xx 応答コードはサーバーエラーを示します。API ゲートウェイ 5xx のエラーには、次のものが含まれます。

500 内部サーバー
502 不正ゲートウェイ
503 サービスは利用できません
504 エンドポイントリクエストがタイムアウトしました

解決策

開始する前に、API Gateway のエラーをトラブルシューティングするために Amazon CloudWatch Logs をオンにする手順に従ってください。

CloudWatch Logs を使用して、API Gateway からの 5xx エラーを見つけることができます。API Gateway メトリクス 5XXError は、一定期間にキャプチャされたサーバー側エラーの数をカウントします。

**注記:**AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、最新の AWS CLI バージョンを使用していることを確認してください。

500 エラー: 内部サーバーエラー

このエラーは、次のいずれかのシナリオが原因で発生する可能性があります。

AWS Lambda 関数コードのエラー
ステージ変数を使用する権限がない
HTTP ステータスコードのマッピングが正しくないか、見つからない
スロットリングに関する問題
POST の HTTP メソッドが未定義です
Lambda 権限
Lambda 関数の JSON 形式の問題
バックエンドのペイロードサイズが 10 MB を超える
プライベートエンドポイント統合
内部サービスの障害

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": "..."
}

バックエンドのペイロードサイズが 10 MB を超える

バックエンドペイロードの最大サイズは 10 MB です。サイズを大きくすることはできません。バックエンドのペイロードサイズが 10 MB のデフォルトクォータを超えないようにしてください。

プライベートエンドポイント統合

プライベート API エンドポイントを使用している場合は、API Gateway のプライベート統合も設定する必要があります。指示に従って API Gateway のプライベートインテグレーションをセットアップします。

内部サービスの障害

AWS に内部サービスの問題が発生した場合、500 エラーが表示される可能性があります。AWS または API Gateway サービス内で問題が解決するまで待ってから、指数関数的バックオフを使用してリクエストを再試行してください。

502 エラー:不正なゲートウェイ

502 エラーコードは、API ゲートウェイが統合している 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 タイムアウトエラーをトラブルシューティングする方法」を参照してください。