ステータスコードは飾りではなくプロトコルの契約
HTTP ステータスコードは機械が読む制御フローであり、インターネットの半分がそこで分岐します。ブラウザはリダイレクトを追うかエラーページを出すかを決め、キャッシュと CDN はレスポンスを保存するかを決め、検索クローラは URL をインデックスに残すか消すかを決め、HTTP クライアントライブラリは再試行するかを決め、監視システムは誰かを呼び出すかを決めます。JSON ボディにエラーメッセージを入れて 200 を返す — 最もよくあるステータスコードのアンチパターン — は、それらすべてを一度に打ち負かします。エラーはキャッシュされ、クローラはそれをインデックスし、クライアントライブラリは成功を報告し、障害の最中もエラー率のダッシュボードは緑のままです。
権威ある定義は RFC 9110 "HTTP Semantics"(2022)にあります。旧来の RFC 7231 一族を統合・置換したものです。最初の桁が契約を担います。1xx は情報、2xx は成功、3xx はリダイレクト、4xx はクライアントの誤り、5xx はサーバーの誤り。この分類が重要なのは、仕様に明示的なルールがあるからです: 認識できないコードを受け取ったクライアントは、そのクラスの x00 として扱わなければならない。429 を知らないクライアントは汎用の 400 として処理し、未知の 599 は 500 として扱われます。これこそが、新しいコードが配備済みのソフトウェアを壊さずに生態系へ入れる仕組みであり — 間違ったクラスに私製コードを発明すること(たとえば「成功」を 470 で報告)が、あなたの制御できない中間装置を壊す理由でもあります。4xx/5xx の境界は責任の割り当てでもあります — 誰が呼び出されるかを決めるのです。
リダイレクトを正しく — 301・302・303・307・308
リダイレクトコードが 5 つあるのは、仕様とブラウザの間の 20 年来の不和のせいです。HTTP/1.0 は 301 と 302 をメソッド保存として定義しました。302 でリダイレクトされた POST は、新しい場所へ再 POST されるべきだったのです。ブラウザはこれを無視してメソッドを GET に書き換え、その挙動は広まりすぎて直せませんでした。HTTP/1.1 は争う代わりに現実を成文化しました。「あちらのリソースを GET しに行け」を意味する 303 See Other が作られ(リロード時のフォーム再送信を防ぐ POST-redirect-GET パターンの背骨)、307 Temporary Redirect が本来の厳密な意味 — 同じメソッド、同じボディ、保証付き — を復元し、RFC 7538 が 2015 年に 301 のメソッド保存版の双子である 308 Permanent Redirect でマス目を完成させました。
メンタルモデルは 2x2 の行列です。恒久か一時か、メソッド変更許容かメソッド保存必須かの掛け合わせ。301 と 302 はレガシーの隅(メソッドが GET に変わりうる)、308 と 307 は厳密な隅です。POST・PUT・DELETE を受ける API エンドポイントでは、この区別は飾りではありません — アップロードを 301 でリダイレクトすると、多くのクライアントでボディなしの GET へ静かに変換され、リクエストデータは蒸発します。
恒久性には牙があります。ブラウザは 301 と 308 を積極的に、しばしば無期限にキャッシュします。誤った恒久リダイレクトは、サーバーが送信をやめた後もローカルキャッシュから発火し続けます — ユーザーには、あなたが遠隔で起こせないキャッシュ削除が必要になります。定石はこうです: 危険なリダイレクトはまず 302/307 で配備し、様子を見てから 301/308 へ昇格させる。検索エンジンは 301/308 を「ランキングシグナルを新 URL へ移転」と扱うため、ドメイン移行や HTTPS 化の正解であり、理想的には数か月維持します。
method may → GET method preserved
permanent 301 Moved 308 Permanent Redirect
temporary 302 Found 307 Temporary Redirect
after POST 303 See Other → always GET (PRG pattern)
# Verify what a redirect really does:
curl -si -X POST https://example.com/old | head -3
HTTP/1.1 301 Moved Permanently
Location: https://example.com/new
# many clients will now GET /new — the POST body is gone401 対 403 対 404 — 認証・認可・隠蔽
名前が意味を裏切っています。401 のラベルは "Unauthorized" ですが、実際の意味は未認証です — サーバーはあなたが誰か知らないのです。RFC 9110 はこの意図を構造で表します。401 レスポンスは、どの認証方式を使うべきかをクライアントに伝える WWW-Authenticate ヘッダーを必ず伴わなければなりません。401 は行き止まりではなく、資格情報を添えて再挑戦せよという招待だからです。ブラウザが Basic チャレンジ付きの 401 にログインダイアログで応じるのはそのためで、よくできた API クライアントが 401 を、期限切れアクセストークンの更新と 1 回だけのリクエスト再送のトリガーとして扱うのもそのためです。
403 Forbidden は逆の状況です。認証は成功し、身元も判明していて、それでも答えはノーです。トークンは有効だがスコープが足りない。ユーザーは実在するが管理者ではない。リソースは存在するが他人のものです。運用上の決定的な違いは、同じ資格情報で 403 を再試行しても無意味だということです — 403 で発火するトークン更新ループは、認証サーバーを無駄に叩くバグです。
仕様が明示的に認める第三の選択肢があります。嘘です。あるリソースへの 403 はそのリソースの存在を裏付けますが、存在こそが秘密のこともあります — プライベートリポジトリの名前、ユーザーアカウントの有無、内部の管理パス。RFC 9110 は、リソースを隠したいサーバーが 403 の代わりに 404 を返すことを許しており、GitHub が閲覧権限のないプライベートリポジトリにまさにこれを行うのは有名です。代償はデバッグ性です(権限が欠けた正当なユーザーが、困惑する「not found」を見ることになります)。だからこの選択はセキュリティ対サポート性の本物のトレードオフであり、意図的に決めるのが最善です。
リトライとレート制限 — 429・503・Retry-After
429 Too Many Requests(コア仕様ではなく RFC 6585 で定義)は、プロトコルのバックプレッシャー弁です。リクエストは理解された、ただクライアントが速く送りすぎているだけ。行儀のよい 429 は Retry-After ヘッダーを伴います。形式は 2 つ — デルタ秒(Retry-After: 30)か絶対時刻の HTTP-date — で、クライアントは自分の勝手なスケジュールで再試行するのではなく、これを尊重すべきです。実際の API の多くはクォータのテレメトリヘッダー(X-RateLimit-Limit / Remaining / Reset の一族。RateLimit フィールドとして標準化が進行中)を添えて、クライアントが壁にぶつかった後ではなく、ぶつかる前に自らペースを整えられるようにしています。
そもそも再試行すべきかは 3 つの問いで決まります。この失敗は再試行可能か? 5xx は概ねイエス、4xx は概ねノー — リクエスト自体が欠陥だからで、例外は 408、429、そして(慎重にであれば)425。このメソッドは繰り返しても安全か? GET・PUT・DELETE は冪等と定義されています。送信途中でタイムアウトした POST は見えないところで成功していたかもしれず、盲目的な POST 再試行は二重課金の危険があります — 決済 API が冪等性キーを追加する理由です。再試行の間隔は? ジッター付きの指数バックオフです。同じ固定スケジュールで再試行するクライアントの群れは波として再同期し、回復途上のサーバーを再び押し潰します。
インシデント対応では、5xx の三兄弟がトリアージの地図になります。502 Bad Gateway: プロキシはアップストリームに到達したがゴミが返ってきた — アプリのプロセスを見る(クラッシュ、OOM)。503 Service Unavailable: 意図的な拒否 — 過負荷、メンテナンス、ヘルスチェック失敗。Retry-After を含むことがあります。504 Gateway Timeout: アップストリームが時間内に応答しなかった — 遅いクエリ、デッドロック、枯渇したコネクションプールを見る。
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1751414460
Retry decision cheat sheet:
408, 429, 5xx → retry with exponential backoff + jitter
other 4xx → do not retry; fix the request
POST → only retry with an idempotency key
backoff: 1s → 2s → 4s → 8s (+ random jitter each step)ステータスコードとキャッシュ — 304・ETag・既定でキャッシュ可能なリスト
304 Not Modified は、存在意義のすべてが帯域の節約にある唯一のステータスコードです。流れは条件付き再検証です。サーバーはレスポンスに検証子(validator)— ETag(不透明なバージョン識別子)か Last-Modified の日時 — を付け、キャッシュされたコピーが期限切れになると、クライアントは If-None-Match または If-Modified-Since を添えて再び尋ねます。リソースが変わっていなければ、サーバーはボディなしの 304 で答え、キャッシュは手元のコピーを再び新鮮なものとしてマークし、ペイロードはワイヤを渡りません。ETag には 2 つの強度があります — 弱い検証子(W/ 接頭辞)は意味的な等価性を、強い検証子はバイト単位の同一性を約束し、Range リクエストには後者が必須です — そして古典的な落とし穴: ファイルの inode メタデータから導出される既定の ETag は、ロードバランサーの背後のサーバーごとに異なり、再検証を静かに壊します。
あまり知られていない、より危険な事実: 一部のステータスコードは既定でキャッシュ可能です。RFC 9110 は 200、203、204、206、300、301、308、404、405、410、414、501 をヒューリスティックにキャッシュ可能と定めています — Cache-Control ヘッダーがまったくなくても、キャッシュは Last-Modified からの経過時間の 10 分の 1 といったヒューリスティックで鮮度を推測して保存してよいのです。そう、404 もリストに入っています。本番の障害モード: デプロイが終わる前にリクエストが到着し、CDN が 404 をキャッシュし、ファイルが存在するようになった後も 404 が出続ける — 誰かがパージするまで。一方、302 と 307 はヒューリスティックなキャッシュの対象外です。一時リダイレクトが安全な実験で、恒久リダイレクトが誓約である正確な理由です。
教訓は、既定値に頼らないこと。エラーを含むすべてのレスポンスに明示的な Cache-Control を送りましょう — 404 には 60 秒の TTL、5xx には no-store といった設定が、ミスを短命にしてくれます。
# First request — server tags the response
HTTP/1.1 200 OK
ETag: "v42-a1b2c3"
Cache-Control: max-age=3600
# One hour later — conditional revalidation
GET /app.js HTTP/1.1
If-None-Match: "v42-a1b2c3"
HTTP/1.1 304 Not Modified ← no body: bytes saved
ETag: "v42-a1b2c3"
# Cacheable WITHOUT any Cache-Control header (RFC 9110):
# 200 203 204 206 300 301 308 404 405 410 414 501