Webサイトを見ていて「404 Not Found」を目にしたことがある人は多いでしょう。
この数字がHTTPステータスコードで、サーバーがリクエストをどう処理したかを、クライアントに伝えるためのものです。
APIを設計するときに適切なコードを返すと、利用者や自分たちがデバッグしやすくなります。
この記事では、コードの分類と、開発で特によく使うコードの使い分けを説明します。
ステータスコードの5分類
| 範囲 | 分類 | 意味 |
|---|---|---|
| 1xx | 情報 | リクエストを受け付け、処理を継続中 |
| 2xx | 成功 | リクエストが正常に処理された |
| 3xx | リダイレクト | 別のURLへの移動など、追加の操作が必要 |
| 4xx | クライアントエラー | リクエスト側に問題がある |
| 5xx | サーバーエラー | サーバー側で処理に失敗した |
2xx：成功
- 200 OK：リクエスト成功。
取得（GET）や更新の結果を返すときに使う。 - 201 Created：リソースが新しく作成された。
POSTで作成したとき、Locationヘッダーに新しいリソースのURLを付けるのが一般的だ。 - 204 No Content：成功したが、返す内容がない。
削除（DELETE）の成功時などに使う。
3xx：リダイレクト
- 301 Moved Permanently：恒久的に別のURLへ移動した。
検索エンジンも新しいURLを評価する。
サイトのURLを変更するときに使う。 - 302 Found：一時的な移動。
元のURLは今後も使われることを示す。 - 304 Not Modified：前回取得したときから変更がない。
ブラウザのキャッシュを使ってよいことを伝える。 - 307／308：それぞれ302、301に近い意味だが、リクエストのメソッド（POSTなど）を変えずに転送することを保証する。
4xx：クライアントエラー
- 400 Bad Request：リクエストの形式や内容が不正（JSONの構文エラー、必須項目の不足など）。
- 401 Unauthorized：認証されていない（ログインしていない、トークンが無効）。
- 403 Forbidden：認証はされているが、権限がない。
- 404 Not Found：指定したリソースが存在しない。
- 405 Method Not Allowed：そのURLでは使えないHTTPメソッドを指定した。
- 409 Conflict：リソースの現在の状態と競合している（重複登録など）。
- 422 Unprocessable Content：形式は正しいが、内容が意味的に処理できない（バリデーションエラーなど）。
- 429 Too Many Requests：短時間にリクエストが多すぎる。
Retry-Afterヘッダーで待ち時間を示すことがある。
401と403の違い
混同しやすい組み合わせです。
「あなたが誰か分からない」のが401、「あなたが誰かは分かったが、この操作は許可されていない」のが403です。
なお、リソースの存在自体を隠したい場合に、権限のないユーザーへ404を返す設計もあります。
5xx：サーバーエラー
- 500 Internal Server Error：サーバー内部で想定外のエラーが起きた。
- 502 Bad Gateway：ゲートウェイやプロキシが、上流のサーバーから不正な応答を受け取った。
- 503 Service Unavailable：過負荷やメンテナンスで、一時的に利用できない。
- 504 Gateway Timeout：ゲートウェイが、上流のサーバーの応答を待ってタイムアウトした。
API設計での心構え
- 失敗なのに200を返さない：本文にエラーを書いて常に200を返すと、クライアントやモニタリングが失敗を検知できません。
- エラー本文を統一する：エラーコード、メッセージ、詳細を、決まったJSON形式で返すと、呼び出し側が扱いやすくなる。
- 内部情報を漏らさない：500系のレスポンスにスタックトレースやSQLを含めると、攻撃の手がかりになる。
詳細はログに残し、利用者にはあたりさわりのない説明を返す。 - クライアントとサーバーの責任を区別する：リトライして直る可能性があるのは、多くの場合5xxと429だ。
4xxは、リクエストを直さない限り同じ結果になる。
まとめ
ステータスコードは、「何が起きたか」を機械にも人間にも伝える共通言語です。
主要なコードの意味と使い分けを押さえておくだけで、API設計やトラブルシュートの質は大きく上がります。
覚えきれないコードは、一覧ツールで確認しながら使いましょう。
