HTTPメソッド × ステータスコード早見表
「このAPI、成功時は201？204？」と迷ったときに参照できる表です。RFC 9110の意味づけに沿って、実務でよく出る組み合わせを整理しました。
成功パターン
メソッドごとに典型的な成功コードを選びます。レスポンスボディ有無との相性も要確認です。
成功コードの目安
| メソッド | 主な成功コード | 使いどころ |
|---|---|---|
| GET/HEAD | 200 OK / 304 Not Modified | 取得。条件付きGETで一致したら304（RFC 9110 13.1）。 |
| POST | 201 Created / 202 Accepted / 200 OK | 作成なら201＋Locationヘッダー。非同期受付なら202。既存リソース更新をPOSTで行うなら200も選択肢。 |
| PUT | 200 OK / 204 No Content / 201 Created | 完全置換。ボディを返すなら200、返さないなら204。同じURIが初登場なら201もあり。 |
| PATCH | 200 OK / 204 No Content | 部分更新。ボディを返すなら200、返さないなら204。 |
| DELETE | 200 OK / 204 No Content | 削除。冪等性確保のため、すでに消えていても204/200で返す設計が無難。 |
| OPTIONS | 204 No Content | 通信可否の応答。CORSプレフライトで多用。 |
よく出るエラーコード
仕様に沿ったエラーを返すとクライアントが自動リトライやUXを組みやすくなります。
エラーコードの選び方
| コード | 典型メソッド | 意味とヒント |
|---|---|---|
| 400 Bad Request | 全般 | リクエスト形式エラー。ボディにエラー詳細を。 |
| 401 Unauthorized | 全般 | 認証が必要。WWW-Authenticateヘッダーを返す。 |
| 403 Forbidden | 全般 | 認証は通ったが権限不足。 |
| 404 Not Found | 全般 | URIにリソースなし。DELETEの二度目でも404を返さない設計も多い。 |
| 405 Method Not Allowed | 全般 | そのURIで未サポートのメソッド。Allowヘッダー必須（RFC 9110 15.5.6）。 |
| 409 Conflict | POST/PUT/PATCH/DELETE | 競合（例: 重複キー、状態衝突）。ボディに解決策を書くと親切。 |
| 412 Precondition Failed | PUT/PATCH/DELETE | If-Match/If-Unmodified-Sinceが不一致。悲観・楽観ロックの失敗で使う。 |
| 415 Unsupported Media Type | POST/PUT/PATCH | Content-Typeが未対応。対応してほしい形式を示すと良い。 |
| 422 Unprocessable Content | POST/PUT/PATCH | バリデーションNG。ドメインエラーの詳細をJSONで返すのに便利（RFC 9110 15.5.21）。 |
| 429 Too Many Requests | 全般 | レート制限。Retry-Afterを添える。 |
| 500/503 | 全般 | サーバー内エラー / 一時的に利用不可。503ではRetry-Afterが有効。 |
設計メモ
コードとメソッドの相性を少し意識するだけで、クライアント実装がぐっと楽になります。
運用のコツ
- POSTで作成したらLocationヘッダーで新リソースURIを示す（RFC 9110 10.2.2）。
- 条件付きリクエスト（If-Match/If-None-Match）を併用し、412や304を正しく返すと中間キャッシュとも仲良くできる。
- DELETEは冪等性を意識して、存在しなくても204/200を返す設計を検討する。
- 仕様外のカスタムコードは避け、問題はレスポンスボディで説明する（application/problem+jsonなど）。
まとめ
RFC 9110の意味づけに沿ってコードを選べば、クライアント・キャッシュ・中継が予測しやすくなります。迷ったら201/204/409/412あたりを軸に検討すると整理しやすいです。