HTTPステータスコードの意味と、API障害の切り分け方

導入：「APIが動かない」という報告から調査を始める手順

「APIが動かない」という報告だけでは、原因がサーバー側にあるのか、リクエストの内容にあるのか、認証にあるのかを判断できません。 最初に確認すべき情報は、レスポンスのHTTPステータスコードです。 ブラウザのDevToolsでNetworkタブを開き、該当リクエストの「Status」列を見れば、3桁の数字としてすぐに確認できます。 コマンドラインからは curl -I でヘッダーだけを取得して確認する方法もあります。

$ curl -I https://example.com/api/items
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
Content-Type: application/json

ステータスコードが分かれば、「サーバーの問題」「リクエストの問題」「認証の問題」のどれに該当するかを最初の段階で切り分けられます。 404（Not Found）はよく知られていますが、実務で扱うコードはそれだけではありません。以下で、区分ごとの意味と使い分けを整理します。

1. 実務で目にする機会が多いステータスコード

HTTPステータスコードは、RFC 9110で百の位ごとに5つの区分（クラス）に分けられています。 まずこの区分を把握すると、初めて見るコードでも大まかな意味を推測できます。

2. ステータスコードで障害の原因を切り分ける

ステータスコードは、障害対応における最初のトリアージ（振り分け）に使えます。 4xxであればリクエスト側（クライアントの実装や認証情報）、5xxであればサーバー側（アプリケーション、プロキシ、バックエンド）から調査を始めるのが基本です。

401 vs 403：認証と認可の違い

401と403はどちらも「アクセスできない」結果になりますが、意味と対処法は異なります。

• 401 Unauthorized：有効な認証情報が付いていない状態です。未ログイン、トークンの期限切れ、 Authorizationヘッダーの付け忘れなどが該当します。RFC 9110では、401を返すサーバーはWWW-Authenticate ヘッダーで利用可能な認証方式を示すことが必須とされています。対処は「認証をやり直す」ことです。
• 403 Forbidden：認証はできているものの、そのリソースに対する権限がない状態です。 RFC 9110では「再認証しても結果は変わらない」場合に使うと定義されています。対処は「権限設定（ロールやACL）を見直す」ことです。

両者を混同すると、権限の問題なのにログイン処理を疑い続けるといった調査の遠回りが起こります。 「401なら認証情報」「403なら権限設定」と切り分けるのが原則です。

502 vs 503 vs 504：サーバーダウンの切り分け

502はロードバランサーがバックエンドから不正な応答を受けたとき、503はサーバーが過負荷やメンテナンス中のとき、504はバックエンドからの応答がタイムアウトしたときに返されます。 この違いを理解していれば、「Nginxの設定問題なのか」「アプリサーバーの問題なのか」「DBの応答遅延なのか」を即座に判断できます。

当サイトのHTTPステータスコード検索ツールを使えば、 コード番号を入力するだけで詳細な説明と適切な対処法を確認できます。

3. API設計で押さえておきたいステータスコードの使い分け

ステータスコードの正しい使い分けは、API設計の品質に直結します。ここでは設計時に判断を誤りやすい2点を取り上げます。

ポイント1: APIレスポンスのステータスコードを正しく設計する

「全部200で返して、ボディ内のerrorフラグで判定する」設計はアンチパターンです。 HTTPステータスコードを正しく使い分けることで、フロントエンド側のエラーハンドリングがシンプルになり、 モニタリングツールでのエラー検知も正確になります。

ポイント2: リダイレクトの301と302、308と307を使い分ける

301（恒久的リダイレクト）はSEOの評価を引き継ぎます。ドメイン移行やURL構造の変更に使います。302（一時リダイレクト）はメンテナンスページへの一時誘導やA/Bテストに使います。 間違えるとSEO評価が損なわれるため、選択には注意が必要です。

さらに、APIのようにPOSTやPUTをリダイレクトする場合は、リクエストメソッドが保持されるかどうかにも注意が必要です。 RFC 9110では、301と302を受け取ったクライアントは歴史的経緯からPOSTをGETに変更してもよいとされています。 一方、308 Permanent Redirectと307 Temporary Redirectは、メソッドとボディを変更せずに再送しなければならないと定められています。

POST /api/v1/items HTTP/1.1
Host: example.com
Content-Type: application/json

{"name": "sample"}

HTTP/1.1 308 Permanent Redirect
Location: https://example.com/api/v2/items

この応答を受け取ったクライアントは、同じボディを持つ POST /api/v2/items を再送します。 同じ場面で301を返すと、ブラウザなど多くのクライアントは GET /api/v2/items に変更してボディを捨てるため、 作成処理が実行されません。APIエンドポイントの移転には308（一時的なら307）を選ぶのが安全です。

HTTPステータスコードは、クライアントとサーバー、そして開発者同士の間で共有される共通の語彙です。 各コードの定義を正確に把握しておくことで、障害対応の初動が速くなり、API設計の品質も安定します。 個別のコードの意味を確認したいときは、HTTPステータスコード検索ツールを参照してください。