#はじめに

「APIから404が返ってきた」——この言葉を聞いて、すぐに原因を特定できますか？

HTTPステータスコードは、サーバーからの「返事」です。しかし、この返事の意味を正しく理解していないと、問題の原因がクライアント（自分のコード）にあるのか、サーバーにあるのかすら判断できません。

この記事を読むと、以下のことができるようになります：

  • ステータスコードを見て、何が起きているのかを即座に判断できる
  • 4xx と 5xx の違いを理解し、原因の切り分けができる
  • 実務でよく遭遇するステータスコードの対処法がわかる

#ステータスコードとは

ステータスコードとは、HTTPレスポンスに含まれる3桁の数字で、リクエストの処理結果を表します。

前回の記事で学んだレスポンスの構造を思い出してください。ステータスコードは、レスポンスの1行目（ステータスライン）に含まれています。

HTTP/1.1 200 OK
         ^^^
      ステータスコード

この3桁の数字を見るだけで、「成功したのか」「失敗したのか」「なぜ失敗したのか」がわかります。

#ステータスコードの分類

ステータスコードは、最初の1桁で大まかな意味がわかるように設計されています。

範囲分類意味
1xxInformational処理中（実務ではほぼ見ない）
2xxSuccess成功
3xxRedirectionリダイレクト（別の場所へ転送）
4xxClient Errorクライアント側のエラー
5xxServer Errorサーバー側のエラー

つまり、**4xx が返ってきたら「自分のコードを疑う」、5xx が返ってきたら「サーバーを疑う」**という切り分けができます。

#2xx: 成功レスポンス

リクエストが正常に処理されたことを示します。

#200 OK

最も基本的な成功レスポンスです。リクエストが成功し、レスポンスボディに結果が含まれています。

GET /api/users/1 → 200 OK + ユーザーデータ

#201 Created

新しいリソースが作成されたことを示します。POSTリクエストで新規登録が成功したときに返されます。

POST /api/users → 201 Created + 作成されたユーザーデータ

#204 No Content

リクエストは成功したが、返すデータがないことを示します。DELETEリクエストで削除成功時によく使われます。

DELETE /api/users/1 → 204 No Content（ボディなし）

#3xx: リダイレクト

リクエストを完了するために、追加のアクションが必要なことを示します。

#301 Moved Permanently

リソースが恒久的に新しいURLへ移動したことを示します。SEOにおいて、旧URLの評価を新URLに引き継ぐために使用されます。

GET /old-page → 301 + Location: /new-page

ブラウザは自動的に新しいURLへリクエストを送り直します。

#302 Found

リソースが一時的に別のURLにあることを示します。

GET /login → 302 + Location: /dashboard

ログイン後のリダイレクトなどでよく使われます。

#304 Not Modified

リソースが更新されていないため、キャッシュを使用してよいことを示します。

GET /style.css + If-None-Match: "abc123" → 304 Not Modified

条件付きリクエスト（後のモジュールで学習）と組み合わせて使用されます。

#4xx: クライアントエラー

リクエストに問題があることを示します。 つまり、修正すべきはクライアント側（あなたのコード）です。

#400 Bad Request

リクエストの形式が不正です。JSONの構文エラー、必須パラメータの欠落などが原因です。

POST /api/users
Content-Type: application/json

{"name": "山田"   ← JSONの閉じ括弧がない

→ 400 Bad Request

対処法: リクエストボディの形式やパラメータを確認する

#401 Unauthorized

認証が必要、または認証に失敗したことを示します。ログインしていない、トークンが無効、トークンの有効期限が切れている、などが原因です。

GET /api/users
Authorization: Bearer invalid_token

→ 401 Unauthorized

対処法: 認証トークンの有無と有効性を確認する

#403 Forbidden

認証は成功したが、そのリソースへのアクセス権限がないことを示します。

GET /api/admin/users
Authorization: Bearer valid_user_token（一般ユーザー）

→ 403 Forbidden

対処法: 権限の設定を確認する。401と違い、再ログインしても解決しません。

#404 Not Found

リクエストしたリソースが存在しないことを示します。URLの入力ミス、削除済みのリソースへのアクセスなどが原因です。

GET /api/users/99999（存在しないID）

→ 404 Not Found

対処法: URLのパスやIDを確認する

#405 Method Not Allowed

そのURLに対して使用したHTTPメソッドが許可されていないことを示します。

DELETE /api/users（DELETEが許可されていないエンドポイント）

→ 405 Method Not Allowed

対処法: APIドキュメントで許可されているメソッドを確認する

#422 Unprocessable Entity

リクエストの形式は正しいが、内容が処理できないことを示します。バリデーションエラーでよく使用されます。

POST /api/users
{"email": "invalid-email"}

→ 422 Unprocessable Entity
  {"errors": {"email": "有効なメールアドレスを入力してください"}}

対処法: レスポンスボディのエラーメッセージを確認し、入力値を修正する

#429 Too Many Requests

リクエストの送信頻度が制限を超えたことを示します（レート制限）。

→ 429 Too Many Requests
  Retry-After: 60

対処法: Retry-Afterヘッダーを確認し、指定された時間後に再試行する

#5xx: サーバーエラー

サーバー側で問題が発生したことを示します。 クライアント側の修正では解決できません。

#500 Internal Server Error

サーバー内部で予期しないエラーが発生したことを示します。バグ、設定ミス、例外処理の欠如などが原因です。

GET /api/users

→ 500 Internal Server Error

対処法: サーバーのログを確認する（クライアント開発者の場合はバックエンド担当に報告）

#502 Bad Gateway

サーバーがゲートウェイやプロキシとして動作中に、上流サーバーから無効なレスポンスを受け取ったことを示します。

クライアント → Nginx → アプリサーバー（応答不正）
                 ↓
             502 Bad Gateway

対処法: 上流サーバーの状態を確認する

#503 Service Unavailable

サーバーが一時的にリクエストを処理できない状態であることを示します。メンテナンス中、過負荷状態などが原因です。

→ 503 Service Unavailable
  Retry-After: 3600

対処法: 時間をおいて再試行する

#504 Gateway Timeout

ゲートウェイやプロキシがタイムアウトしたことを示します。上流サーバーからの応答が遅すぎる場合に発生します。

→ 504 Gateway Timeout

対処法: サーバーの負荷状態やタイムアウト設定を確認する

#実務で役立つ判断フローチャート

エラーが発生したとき、以下の順序で原因を切り分けます：

ステータスコードを確認
    │
    ├── 2xx → 成功！レスポンスボディを確認
    │
    ├── 3xx → リダイレクト。LocationヘッダーでURLを確認
    │
    ├── 4xx → 自分のコードを確認
    │    ├── 400: リクエストの形式
    │    ├── 401: 認証トークン
    │    ├── 403: 権限設定
    │    ├── 404: URLやパラメータ
    │    └── 422: 入力値のバリデーション
    │
    └── 5xx → サーバー側の問題
         ├── 500: バックエンド担当に報告
         ├── 503: 時間をおいて再試行
         └── 504: タイムアウト設定を確認

#DevToolsで確認してみよう

  1. DevToolsのNetworkタブを開く
  2. リクエストを発生させる
  3. 一覧の「Status」列でステータスコードを確認
  4. エラーの場合は、Responseタブでエラー詳細を確認

ステータスコードは色分けされています：

  • 緑: 2xx（成功）
  • 青/グレー: 3xx（リダイレクト）
  • オレンジ/赤: 4xx, 5xx（エラー）

#まとめ

  • ステータスコードは3桁の数字で、リクエストの結果を表す
  • 最初の1桁で大まかな意味がわかる: 2xx=成功、3xx=リダイレクト、4xx=クライアントエラー、5xx=サーバーエラー
  • 4xxは自分のコードを確認、5xxはサーバー側の問題
  • 実務でよく遭遇するのは: 200, 201, 204, 301, 302, 400, 401, 403, 404, 500, 503

#次のステップ

ステータスコードの意味がわかったところで、次はHTTPヘッダーを詳しく見ていきましょう。「Content-Typeって何？」「Authorizationヘッダーはどう設定する？」——ヘッダーを理解することで、リクエストとレスポンスの「追加情報」が読み解けるようになります。

#参考リンク