HTTPステータスコードの分類と実務活用：API設計・キャッシュ・セキュリティまで網羅
エバープレイ編集部はじめに — ステータスコードとは何か
ステータスコード（HTTPステータスコード）は、HTTPプロトコルでクライアント（ブラウザやAPIクライアント）とサーバが通信する際に、サーバ側がレスポンスに含めて返す3桁の数字です。レスポンスの結果を簡潔に示し、クライアント側が次にどう振る舞うべきか（成功／リダイレクト／クライアントエラー／サーバエラーなど）を伝達します。正しい理解はWeb開発、API設計、SEO、キャッシュ戦略、障害対応に不可欠です。
ステータスコードの分類（1xx〜5xx）
- 1xx（情報）：処理中を示す暫定的な応答（例：100 Continue、101 Switching Protocols）。通常はクライアントに追加の処理を許可するために使われます。
- 2xx（成功）：リクエストが正常に完了したことを示す。代表的なものに200 OK、201 Created、204 No Contentなど。
- 3xx（リダイレクト）：クライアントに別のリソースへ移動するよう指示。301、302、303、307、308などがあり、恒久的／一時的やHTTPメソッドの扱いの差が重要です。
- 4xx（クライアントエラー）：クライアント側の問題。400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、429 Too Many Requestsなど。
- 5xx（サーバエラー）：サーバ側の問題。500 Internal Server Error、502 Bad Gateway、503 Service Unavailable、504 Gateway Timeoutなど。
主要なステータスコードの意味と注意点
- 200 OK：リクエスト成功。通常はレスポンス本文を返す。GETやPOSTの成功応答として多用。
- 201 Created：リソースが作成された。Locationヘッダで新しいリソースのURIを返すのが慣例（RESTのPOST/PUT時）。レスポンス本文に作成されたリソース表現を含めることも可能。
- 202 Accepted：処理を受け付けたが未完了（非同期処理）。処理結果は後で別途確認する必要がある。
- 204 No Content：成功したが本文を返さない。PUT/DELETEの成功応答に使われることが多い。レスポンスボディを含めてはいけない。
- 301 Moved Permanently：恒久的に別のURIへ移動。SEO的にはリンク評価（PageRankなど）を引き継ぐとされる（実装や検索エンジンの挙動に依存）。キャッシュ可能。
- 302 Found / 303 See Other / 307 Temporary Redirect / 308 Permanent Redirect：一時・恒久の差、かつHTTPメソッド（GET/POSTなど）を変えるか否かがポイント。例えば303はPOST後にGETで取得させる用途、307/308はメソッドを保持するリダイレクト。
- 304 Not Modified：If-None-Match / If-Modified-Since等の条件付きリクエストに対する応答で、リソースは変更されていないため本文は返さずキャッシュを使わせる。ボディを含めないこと。
- 400 Bad Request：構文エラーや無効なリクエスト。
- 401 Unauthorized：認証が必要（WWW-Authenticateヘッダを含める）。「認可されていない」ではなく「認証が必要」を意味。
- 403 Forbidden：認証済みでもアクセスが許可されない。認証と権限の違いに注意。
- 404 Not Found：要求されたリソースが存在しない。APIではリソースIDが無効な場合によく使う。
- 405 Method Not Allowed：そのリソースでそのHTTPメソッドは許可されていない（Allowヘッダで許可メソッドを返すのが規定）。
- 409 Conflict：競合（例：楽観的ロックで更新競合が起きた場合）。
- 412 Precondition Failed / 428 Precondition Required：条件付きリクエストが満たされない、または条件付きリクエストを要求する場合に使う（競合回避のためなど）。
- 413 Payload Too Large / 431 Request Header Fields Too Large：リクエストボディやヘッダが大きすぎる。
- 429 Too Many Requests：レート制限。Retry-Afterヘッダで再試行推奨時間を返すことが望ましい。
- 500 Internal Server Error：サーバ内部エラー。内部構造や例外の詳細をクライアントに公開しないこと（セキュリティ観点）。
- 502/503/504：プロキシやバックエンド不具合、メンテナンス（503はサービス停止・メンテナンスに使う。Retry-After指定可能）、ゲートウェイのタイムアウトなど。
- 451 Unavailable For Legal Reasons：法的理由でアクセス不可（検閲など）。
- WebDAVや拡張コード：207 Multi-Status、422 Unprocessable Entity、102 Processingなどは拡張仕様やWebDAV由来のステータス。用途を理解して使う。
- 冗談系（例：418 I'm a teapot）：RFC 2324のエイプリルフールRFC由来だが、認識しておくとトラブルの説明で役立つ場合がある。
実運用でのポイントとベストプラクティス
- 意味に忠実に使う：クライアントや検索エンジンはステータスコードをもとに挙動を変える。例：404であれば検索エンジンはページをインデックスしないことが多い。200を常に返して錯誤的に表示するのは避ける。
- POSTと201の扱い：リソースが作成されたら201とLocationヘッダで新しいURIを返す。API設計の一貫性が重要。
- 非同期処理と202：即時に完了しない処理は202を返し、結果取得方法を文書化する（ジョブIDやポーリング／Webhookなど）。
- リダイレクトの正しさ：恒久的な移動は301/308、短期移動は302/307。POST→GETのようにメソッドを変えたい場合は303を使用。
- キャッシュとの連携：ETag/If-None-MatchやLast-Modified/If-Modified-Sinceと304を正しく使うことで帯域と応答時間を削減。304はボディを返さない点に注意。
- 認証と認可の差：401（認証要求）と403（アクセス禁止）は明確に使い分ける。APIクライアントの挙動（リトライやログイン遷移）が異なる。
- レート制限の設計：429でRetry-Afterを返す、あるいはヘッダで残り上限やリセット時間を通知することでクライアントの扱いやすさが向上。
- エラーメッセージの設計：開発者向けには詳細なエラー情報（エラーコード、説明、問題解決リンク）を返す。ユーザ向けには内部情報を隠す。
- ログと監視：4xx/5xxの発生状況を監視し、閾値越えでアラートを出す。どのエンドポイントでどのステータスが出ているかを可視化する。
- 国際化・法的対応：法的ブロッキングが必要な場合は451を利用し、ユーザに理由と問い合わせ先を示す。
API設計でのステータスコードの使い分け（実践例）
- GET /items/123 → 200（存在） / 404（存在しない） / 401（認証必要）
- POST /items → 201（作成、Locationヘッダ） / 400（バリデーション） / 409（競合）
- PUT /items/123 → 200（更新後の表現） / 204（ボディ不要） / 404（対象なし） / 412（条件付き更新失敗）
- DELETE /items/123 → 204（削除成功、ボディ不要） / 404（対象なし）
- 非同期処理開始 → 202（ジョブ受付） + ジョブIDを返しポーリングやWebhookで完了通知
キャッシュと条件付きリクエストの関係
ETagやLast-Modifiedを用いた条件付きリクエストにより、クライアントはサーバに対して「前回取得したバージョンから変更があるか」を問い合わせます。サーバが変更なしと判断すれば304 Not Modifiedを返し、ボディを省略してクライアントにキャッシュを使わせます。これにより帯域とレスポンス時間を大幅に削減できます。条件付きPUT/DELETEでの衝突回避（If-Matchヘッダ等）も有効です。
セキュリティと情報漏洩の注意
500系エラーやスタックトレースをそのままクライアントに返すのは避けましょう。内部情報（SQL、ファイルパス、フレームワークの例外詳細等）は攻撃者に利用される可能性があります。クライアントには一般的なエラーメッセージを返し、詳細はサーバ側ログで保持して調査するのが安全です。
カスタムステータスコードは避けるべきか
独自の3桁コードを定義することは技術的には可能ですが、クライアントやプロキシ、CDN、監視ツールが理解せず不具合や誤動作を招く可能性があるため推奨されません。特別な要件がある場合は、既存の5xx/4xxの範囲で意味を工夫する、あるいはレスポンス本文で拡張情報（独自のAPIエラーコード）を返す方法が一般的です。
デバッグとトラブルシューティングのコツ
- まずステータスコードを確認：クライアントがどう受け取っているかを把握することが最優先。
- レスポンスヘッダを見る：Location、WWW-Authenticate、Retry-After、Allow、ETagなどは重要な手がかり。
- 再現手順を固める：同一条件でcurlやPostmanなどで再現し、プロキシやCDNの影響を切り分ける。
- ログを突き合わせる：サーバログ、アクセスログ、アプリケーションログを横断して原因を特定する。
まとめ
ステータスコードは単なる数字ではなく、クライアントとサーバ間の「合図」です。設計段階で適切に選択・運用することで、パフォーマンス改善、堅牢なAPI設計、ユーザ体験・SEOの向上、運用の効率化につながります。RFCやIANAの仕様を参照し、意味に忠実に使うことで、予期しない副作用を減らしましょう。
参考文献
- RFC 7231 — Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
- RFC 7232 — Conditional Requests
- RFC 7233 — Range Requests
- RFC 7235 — Authentication
- RFC 6585 — Additional HTTP Status Codes
- RFC 7538 — Permanent Redirect (308)
- RFC 7725 — 451 Unavailable For Legal Reasons
- RFC 4918 — WebDAV (Multi-Status, Unprocessable Entity など)
- IANA — HTTP Status Code Registry
投稿者プロフィール
