はじめに
Lambda統合したAPI Gatewayの実行時に発生しうるエラーコードについて、実際に確認したものを備忘として記載します
エラーコード別の切り分け概要
| ステータスコード | 分類 | 主な原因 |
|---|---|---|
| 401 / 403 | 認証・認可エラー | トークン不備、IAM設定不備 |
| 400 / 404 | リクエストエラー | クライアント仕様不備 |
| 500 | 内部エラー | Lambda設定・実装不備 |
| 502 | 接続エラー | バックエンド接続不可 |
| 503 | サービスエラー | 高負荷・AWS障害 |
| 504 | タイムアウト | Lambda実行時間超過 |
401 / 403 認証・認可エラー
判断基準
- API Gateway もしくは Lambda 実行時に拒否される
- Lambda のログが出力されない、または即時終了する
想定される原因
- 認証トークンの有効期限切れ
- IAM アクセスキー/シークレットキーの設定不備
- IAM ポリシーの権限不足
- API Gateway のリソースポリシーによる明示的拒否
確認ポイント
- API Gateway の Access Log / Execution Log
- Lambda の CloudWatch Logs
- IAM ロールおよびポリシー設定
- Secret Manager / 環境変数の値
アラート内容例と対応
例1：認証情報不備（401）
ログ：Session expired or invalid
対応
- 認証情報が無効、または期限切れ
- Lambda 環境変数および Secret Manager の値を確認
例2：認証トークン不備（403）
ログ：The security token included in the request is invalid
対応
- トークン値が不正
- Lambda 環境変数と Secret Manager の設定値を確認
例3：IAM ロール権限不足（403）
ログ：An error occurred (AccessDeniedException) when calling the XXXXX operation
対応
- Lambda に付与されている IAM ロールの権限が不足しているため必要なアクションがポリシーに含まれているか確認
例4：リソースポリシーによる拒否（403）
ログ：An explicit deny in a resource-based policy
対応
- API Gateway のリソースポリシーで IP 制限されているため 設定されている IP と実際のアクセス元 IP を確認
400 / 404 リクエストエラー
判断基準
- 認証は通過しているが、API が処理されない
- Lambda は実行されない、または即終了
想定される原因
- クライアント側のリクエスト仕様不備
- パラメータ不足・形式誤り
- 存在しないリソースへのアクセス
対応
- フロントエンド/クライアント側の呼び出し仕様を確認
- API 定義との不一致を確認
500 内部エラー
判断基準
- Lambda が実行されている
- CloudWatch Logs に例外が出力される
想定される原因
- Lambda 内の実装不備
- 環境変数や Secret Manager の参照ミス
アラート例
パラメータ不正（500）
ログ：Invalid length for parameter XXXXX, value: 0, valid min length: 1
対応
- Lambda 内で空文字が代入されているため環境変数・Secret Manager の値を確認
リソース未検出（500）
ログ：Secrets Manager can't find the specified secret
対応
- Secret Manager 名が誤っているためLambda 環境変数の値を確認
502 / 503 / 504 サーバー・タイムアウト系エラー
502 Bad Gateway
- バックエンド（Lambda / HTTP 接続先）に接続できない
- ネットワーク設定やエンドポイントを確認
503 Service Unavailable
- 一時的な高負荷
- API Gateway 側の障害やスロットリングの可能性
504 Gateway Timeout
- Lambda 実行時間超過
- 外部 API 呼び出しの遅延
障害対応フロー
- エラーステータスコードを確認
- API Gateway の Access Log / Execution Log を確認
- Lambda の CloudWatch Logs を確認
- IAM / リソースポリシー / 環境変数を確認
- 必要に応じてエラー発生元へ連絡
- 原因不明の場合は AWS サポートへ問い合わせ
併せて記憶しておきたいこと
4xx error、5xx errorをcloud watchアラートで検出したい場合は以下を利用します
名前空間：AWS/ApiGateway
メトリクス名：4XXError/5XXError
また、Lambdaと統合している場合、APIアクセスログだけでなくLambdaのログにもエラーの詳細が出力されていることも考えられるためそちらも併せて確認します
おわり