HTTPステータスコードの設計指針 — REST APIでの適切な使い方
HTTPステータスコードは単なる数字ではなく、APIの設計思想を伝える重要なインターフェースです。適切なコードを返すことでクライアントは処理の成否を即座に判断でき、デバッグが容易になります。
2xxの使い分け
200 OKはGET・PUT・PATCHの成功に使います。201 CreatedはPOSTでリソース作成成功時に使い、Locationヘッダーで作成されたリソースのURLを返します。204 No ContentはDELETE成功・副作用なしのPUT・副作用なしのPATCHで使います。202 Acceptedはキューへのエンキューなどですぐにはレスポンスが返せない非同期処理の受理を示します。
4xxのベストプラクティス
400 Bad Requestはリクエストの構文エラー、422 Unprocessable ContentはバリデーションエラーやビジネスロジックのNG、401はAuthorizationヘッダーがない・無効、403は認証済みだがアクセス権なし、409 Conflictは重複登録・楽観的ロック競合、429 Too Many Requestsはレートリミット超過に使います。エラーレスポンスのボディにはエラーコードと人間が読めるメッセージを含めるとデバッグが楽になります。
リダイレクトコードの違い
301/308は恒久的リダイレクト（SEO評価が引き継がれる）、302/307は一時的リダイレクト（SEO評価は引き継がない）です。301/302はブラウザがPOSTをGETに変換することがありますが、307/308はメソッドを保持します。APIのエンドポイントを移行する場合は308を使うと、クライアントがPOSTリクエストをそのまま新URLに送り直してくれます。
5xxのハンドリング
5xxはすべてサーバー側の問題です。500 Internal Server Errorは予期しない例外のフォールバック、502 Bad GatewayはリバースプロキシがバックエンドとTCP接続できない・無効なHTTPレスポンスを受け取った、503 Service Unavailableはメンテナンス・過負荷でRetry-Afterヘッダーで再試行タイミングを示す、504 Gateway Timeoutはバックエンドの処理タイムアウトです。クライアントは5xxに対してエクスポネンシャルバックオフでリトライするのが一般的です。