API通信において 400系（クライアントエラー） や 500系（サーバーエラー） が発生する場合、それぞれの原因を理解し、適切に対処することが重要です。
本記事では、各エラーコードの意味・主な原因・解決策を解説します。
1. 400系（クライアントエラー）
クライアント側のリクエストに誤りがある場合に発生するエラーです。
400 Bad Request
意味: リクエストが無効（フォーマットミスや不正なデータ）
主な原因
- JSONフォーマットの誤り
- 必須パラメータが不足
- データ型が不正（例:
intなのにstringを送信） - エンコードエラー（文字化け）
- リクエストボディが空
- APIのバージョン違い
解決策
- リクエストデータを API仕様書と照合 する
- JSONのフォーマットを 検証ツール（JSONLintなど） でチェック
- APIのバージョンを確認する
エラーレスポンス例
jsonコピーする編集する{
"status": "error",
"message": "Invalid request format",
"details": {
"field": "email",
"error": "Email is required"
}
}
401 Unauthorized
意味: 認証に失敗（APIキーやトークンが無効）
主な原因
- 認証情報（APIキー、JWTトークン）が間違っている
- トークンの有効期限が切れている
- 認証ヘッダーがない
- OAuthの認証フローに問題がある
解決策
- APIキーやトークンを再発行
- ヘッダーに正しく Authorization を設定
- JWTの有効期限を確認
エラーレスポンス例
jsonコピーする編集する{
"status": "error",
"message": "Invalid token"
}
403 Forbidden
意味: 認証は成功したが、アクセス権限がない
主な原因
- APIキーにアクセス権がない
- CORS（クロスオリジン制約）によるブロック
- IP制限
- 特定のリソースへのアクセス禁止（例: 管理者専用）
解決策
- APIの アクセス権限（RBAC） を確認
- CORS設定を確認
- IP制限がある場合は許可リストを確認
エラーレスポンス例
jsonコピーする編集する{
"status": "error",
"message": "You do not have permission to access this resource"
}
404 Not Found
意味: リソースが見つからない（URL間違い）
主な原因
- エンドポイントが存在しない
- URLのパスパラメータが間違っている
- リソースが削除されている
解決策
- API仕様書 と照らし合わせて URLを確認
/users/{id}などの IDが有効か確認- デバッグログで APIがどのURLを呼び出しているか確認
エラーレスポンス例
jsonコピーする編集する{
"status": "error",
"message": "User not found"
}
405 Method Not Allowed
意味: 対応していないHTTPメソッドを使用
主な原因
GETしか対応していないAPIにPOSTで送信- CORSの設定ミス
解決策
- APIが対応する HTTPメソッドを確認
- クライアント側のリクエスト設定を修正
2. 500系（サーバーエラー）
サーバー側の問題により、リクエストが処理できない場合に発生するエラーです。
500 Internal Server Error
意味: サーバー内部エラー（一般的なエラー）
主な原因
- プログラムのバグ
- データベース接続エラー
- Nullポインタ例外（未定義の変数を参照）
- メモリ不足
- ログ出力時のエラー
解決策
- サーバーログを確認
- DB接続設定をチェック
- 例外処理 (try-catch) を強化
エラーレスポンス例
jsonコピーする編集する{
"status": "error",
"message": "An unexpected error occurred"
}
502 Bad Gateway
意味: リバースプロキシ（Nginx, AWS ALB など）がバックエンドと通信できない
主な原因
- バックエンドAPIが落ちている
- サーバー間のネットワークエラー
- ロードバランサーの設定ミス
解決策
- バックエンドサーバーが 動作しているか確認
- Nginxやロードバランサーの設定を確認
curlコマンドでAPIが生きているかテスト
テストコマンド
bashコピーする編集するcurl -I http://backend-server/api/health
503 Service Unavailable
意味: サーバーが一時的に利用不可
主な原因
- メンテナンス中
- 過負荷（リクエストが多すぎる）
- データベースの接続上限超過
解決策
- サーバーの負荷を確認 (
top,htop,vmstat) - スケールアウト（負荷分散）を検討
- レートリミット（制限）を実装
504 Gateway Timeout
意味: バックエンドAPIの応答が遅い
主な原因
- DBクエリの処理時間が長すぎる
- サーバーのレスポンスが遅い
- ロードバランサーのタイムアウト設定
解決策
- クエリの最適化 (
EXPLAIN ANALYZEで遅いSQLを特定) - APIのタイムアウト設定を調整
- 負荷分散（スケールアップ/スケールアウト）を検討
3. まとめ
| エラーコード | 原因 |
|---|---|
| 400 | JSONフォーマットミス、必須パラメータ不足 |
| 401 | 認証エラー（APIキー、トークン不正） |
| 403 | アクセス権限がない |
| 404 | URL間違い、リソースが存在しない |
| 405 | HTTPメソッド間違い |
| 500 | サーバー内部エラー、コードバグ |
| 502 | リバースプロキシがバックエンドに接続できない |
| 503 | サーバー過負荷、メンテナンス中 |
| 504 | APIの処理が遅すぎる（タイムアウト） |
APIのエラーハンドリングを適切に行うことで、信頼性の高いシステムを構築できます。適切なエラーメッセージと対策を実装し、スムーズなAPI運用を目指しましょう。
コメントを残す