REST API設計者が知るべきHTTPステータスコード完全解説

RFC 9110（HTTP Semantics）で規定されたステータスコードは、クライアント、リバースプロキシ、CDN（エッジサーバー）、そしてオリジンサーバー間で合意された世界標準のシグナルプロトコルです。RESTful API設計においてステータスコードは、単なる処理の成否にとどまらず、レスポンスがキャッシュ可能か、リトライが安全に行えるか、再認証が必要かといった極めて重要なコンテキストを伝達します。

すべてのエラーを200 OKでラップしてレスポンスボディの中にエラーメッセージを入れるアンチパターンは、フロントエンドのインターセプター処理やCDNのエッジキャッシュ層を完全に無力化し、運用監視システムのアラート検知を麻痺させます。

• 1xx（情報提供）: リクエストを受領し、処理を継続していることを示します（例: WebSocket接続への切り替え時に返る101 Switching Protocols）。
• 2xx（成功）: クライアントのリクエストがサーバー側で正常に受理・処理されたことを示します（汎用的な200 OK、リソースが新規作成された際の201 Created、ボディを持たない204 No Content）。
• 3xx（リダイレクト）: 要求を完了するために、クライアント側で追加のアクション（別URLへの再リクエストなど）が必要であることを示します。
• 4xx（クライアントエラー）: パラメータの不正や認証不足など、クライアント側に起因する問題でリクエストを処理できないことを示します。
• 5xx（サーバーエラー）: 有効なリクエストであるにもかかわらず、サーバー内部のバグやインフラ障害により処理に失敗したことを示します。

1. 401 Unauthorized vs 403 Forbidden:
   • 401 Unauthorized: 正確には「未認証（Unauthenticated）」を意味します。認証トークンが存在しないか期限切れであり、レスポンスには認証方法を示すWWW-Authenticateヘッダーを含める必要があります。
   • 403 Forbidden: ユーザーの身元は確認できているものの、そのリソースに対する権限（Permission）が不足していることを示します。同一の認証情報で再試行しても結果は変わりません。
2. 404 Not Found vs 410 Gone:
   • 404 Not Found: 指定されたURIにリソースが存在しない状態。一時的な欠落の可能性もあるため、検索エンジンのクローラーは後日再巡回を試みます。
   • 410 Gone: リソースが意図的かつ恒久的に削除されたことを明示します。検索エンジンのクローラーは、通常の404よりもはるかに迅速にURLをインデックスから除外します。
3. 301 Moved Permanently vs 308 Permanent Redirect:
   • 従来の301は、古いクライアントがリダイレクト時に元のPOSTメソッドを誤ってGETメソッドへ書き換えてしまう歴史的問題がありました。
   • 308 Permanent Redirectは、リダイレクト後も元のHTTPメソッドとリクエストボディを厳密に変更しないことが規格で保証されています。

RFC 7807を改定して2023年に承認されたRFC 9457は、application/problem+jsonメディアタイプを通じて統一されたJSONエラースキーマを規定しています：

{
  "type": "https://api.devutils.run/errors/insufficient-balance",
  "title": "アカウントの残高が不足しています",
  "status": 403,
  "detail": "現在の保有クレジットは30ですが、この操作の実行には50クレジットが必要です。",
  "instance": "/account/12345/transactions/abc"
}

• 安全なメソッド（Safe）（GET, HEAD, OPTIONS）: サーバーのリソース状態を一切変更しない読み取り専用の操作です。
• 冪等なメソッド（Idempotent）（GET, PUT, DELETE, HEAD）: 同じリクエストを1回実行しても複数回連続して実行しても、サーバーの最終状態が同一になる性質を指します。
• 非冪等なメソッド（Non-Idempotent）（POST, PATCH）: 2回呼び出すと二重決済や重複レコードが生成される危険性があります。

ネットワークの一時的なタイムアウトに伴うクライアントのリトライ処理は、必ず冪等性が保証されているリクエストに対してのみ実行するのが堅牢なシステム設計の基本です。