HTTPステータスコード：意味と使い分け
200と404の向こう側へ。API開発者のための実践的ステータスコードガイド。
APIが200を返します。レスポンスボディには {"error": "Not found"} とあります。
これは間違っています。ステータスコードには理由があります。適切に使いましょう。
5つのカテゴリー
1xx — 情報。実際にはほとんど見かけません。
2xx — 成功。リクエストが成功しました。
3xx — リダイレクト。他の場所へ行ってください。
4xx — クライアントエラー。あなたが何か間違えました。
5xx — サーバーエラー。私たちが何か間違えました。
実際に使うコード
成功（2xx）
200 OK — 標準的な成功。データを返すGETリクエストに使います。
201 Created — リソースが作成されました。何かを作成する成功したPOSTの後に使います。
204 No Content — 成功、でも返すものはなし。データを返さないDELETEや更新に使います。
クライアントエラー（4xx）
400 Bad Request — リクエストが不正。無効なJSON、必須フィールドの欠落、間違ったデータ型。
401 Unauthorized — 認証なし。ユーザーはログインが必要です。
403 Forbidden — 認証済みだが許可されていない。ユーザーは存在するが権限がない。
404 Not Found — リソースが存在しない。定番。
409 Conflict — リクエストが現在の状態と競合。重複ユーザー名、バージョンの不一致。
422 Unprocessable Entity — 構文的には正しいが意味的に間違い。有効なJSONだがビジネスルールに違反。
429 Too Many Requests — レート制限。落ち着いてください。
サーバーエラー（5xx）
500 Internal Server Error — 一般的なサーバー障害。何かがクラッシュしました。
502 Bad Gateway — 上流サーバーが失敗。あなたのサーバーは問題ないが、依存するものが問題。
503 Service Unavailable — 一時的にダウン。メンテナンスか過負荷。
504 Gateway Timeout — 上流サーバーが時間内に応答しなかった。
よくある間違い
ボディにエラーがあるのに200。 エラーなら、エラーステータスコードを使いましょう。成功したか知るためにクライアントにボディを解析させないでください。
検証エラーに500。 ユーザーが不正なデータを送信？それは400か422で、500ではありません。サーバーは壊れていません——リクエストが壊れています。
401 vs 403の混乱。 401は「あなたは誰？」403は「誰だか知ってるけど、ダメ。」
何でも404。 「見つからない」が常に正しい答えとは限りません。間違ったメソッド？405。レート制限？429。
APIの設計
具体的に。クライアントは特定のエラーをインテリジェントに処理できます。汎用エラーは汎用処理を意味します。
ボディにエラー詳細を含めましょう：
{
"error": "validation_failed",
"message": "Email format is invalid",
"field": "email"
}
ステータスコードは問題のカテゴリーを伝えます。ボディが具体的に説明します。
クライアントとしてのステータスコード処理
2xx — レスポンスを解析、通常通り進行。
4xx — あなたのミス。ログ、ユーザーに表示、リクエストを修正。
5xx — サーバーのミス。バックオフでリトライかもしれない。アラートかもしれない。
3xx — リダイレクトを自動で追跡（ほとんどのHTTPクライアントはそうします）。
200だけをチェックしないでください。成功（2xx）をチェックし、他のケースを適切に処理しましょう。
ステータスコードはコミュニケーションです。正しく使えばAPIは自己文書化されます。誤用すればデバッグは当て推量になります。