HTTP ステータスコード

HTTP ステータスコードとは

HTTP ステータスコードは、サーバーがクライアントに返す 3 桁の数値で、リクエストの処理結果を表す。1xx〜5xx の 5 カテゴリに分類される。

カテゴリ

カテゴリを以下にまとめる。

カテゴリ	意味	例
1xx	情報	100 Continue
2xx	成功	200 OK, 201 Created
3xx	リダイレクト	301 Moved Permanently, 304 Not Modified
4xx	クライアントエラー	400 Bad Request, 404 Not Found
5xx	サーバーエラー	500 Internal Server Error, 503 Service Unavailable

よく使うステータスコード

よく使うステータスコードを以下にまとめる。

コード	意味	使い方
200	OK	GET の成功
201	Created	POST でリソース作成
204	No Content	DELETE の成功 (ボディなし)
301	Moved Permanently	URL の恒久的な移動
304	Not Modified	キャッシュが有効
400	Bad Request	バリデーションエラー
401	Unauthorized	認証が必要
403	Forbidden	権限がない
404	Not Found	リソースが存在しない
409	Conflict	競合 (楽観ロック失敗)
429	Too Many Requests	レート制限
500	Internal Server Error	サーバー内部エラー
502	Bad Gateway	上流サーバーのエラー
503	Service Unavailable	一時的に利用不可

401 を返すときは、RFC 9110 が WWW-Authenticate ヘッダーの送信を必須としている。どの認証方式で出し直せばよいかをクライアントに伝えるためだ。認証は通っているが権限が足りない場合は 403 で、こちらにヘッダーの要求はない。

API Gateway のステータスコード

API Gateway では、Lambda が返したコードとは別に、API Gateway 側の事情で決まるコードがある。まず統合タイムアウト (既定 29 秒) を超えると 504 になる。これは Lambda 自身のタイムアウトではなく API Gateway の制限なので、関数側のタイムアウトを 900 秒に設定していても 29 秒で切られる。次に Lambda プロキシ統合では、関数が未処理例外を投げた場合や statusCode を含む所定の JSON 形式以外を返した場合に 502 になる。加えてスロットリング時は 429、Cognito ユーザープールオーソライザーでトークンが欠落・無効なら 401 だ。障害調査では、アプリのバグと API Gateway の制約のどちらを見ているのかを最初に切り分ける。

リダイレクトの使い分け

恒久的な URL 移動には 301、一時的な移動には 302 を使う。301 なら移転先が正規の URL であることを検索エンジンにも伝えられる。

落とし穴はメソッドの扱いだ。RFC 9110 は 301 と 302 について、歴史的な理由からクライアントが後続リクエストのメソッドを POST から GET に変えてもよいと注記している。つまり POST のリダイレクトでボディが失われ得る。メソッドとボディを保ったままリダイレクトさせたい場合は、一時的なら 307、恒久的なら 308 を使う。この 2 つはメソッドの変更を禁じており、301 / 302 の曖昧さを解消するために用意されたものだ。

リトライの判断

429 (レート制限)、503 (一時的に利用不可)、502 と 504 (上流や統合の異常) はリトライ対象だ。429 と 503 では Retry-After ヘッダーが再試行までの待ち時間を示すので、自前の指数バックオフより優先して尊重する。400 (バリデーションエラー) や 404 (リソースなし) はリクエスト自体を直さない限り何度送っても同じ結果になる。

判断が難しいのは 500 だ。サーバー側の処理がどこまで進んだか分からないため、リトライの可否はメソッドの冪等性で決まる。GET・PUT・DELETE や冪等キーを添えた POST なら送り直してよいが、冪等でない POST を機械的にリトライすると二重登録・二重課金を生む。

HTTP ステータスコードを扱う関連書籍も多い。