rest apiを作成する際に、考慮すべきレスポンスのステータスコード

質問

rest apiを作成する際に、考慮すべきレスポンスのステータスコードをまとめてください

解答

REST API設計でステータスコードをどう使うかは、 **「APIの使いやすさ」「クライアント実装の簡潔さ」「障害時の切り分け」**に直結します。 以下では 必ず押さえるべき主要ステータス REST APIでの使い分けの考え方 を体系的にまとめます。 1. 大分類の全体像（まず俯瞰） 系列 意味 RESTでの役割 2xx 成功 正常系 3xx リダイレクト APIでは原則使わない 4xx クライアントエラー リクエストの問題 5xx サーバエラー API側の問題 2. 2xx（成功系）で考慮すべきもの 200 OK 最も汎用的 GETの成功 PUT/PATCHの成功 処理結果を返す場合 注意： 「とりあえず200」は乱用しない 意味が分かれる場合は他を使う 201 Created リソース作成成功 POSTで新規作成したとき Locationヘッダに作成リソースのURIを含めるのが望ましい POST /users→ 201 CreatedLocation: /users/123 204 No Content 成功だが返すものがない DELETE成功 更新成功だがレスポンスボディ不要 注意： ボディを返してはいけない 3. 3xx（基本的にAPIでは使わない） 原則 REST APIでは ほぼ使わない クライアントが混乱する 例外： 認証フロー（OIDCなど） ファイルDL系 通常のJSON APIでは避ける。 4. 4xx（クライアント起因エラー） 400 Bad Request リクエスト自体が不正 JSON構文エラー 必須パラメータ不足 型不一致 { "error": "invalid_request", "message": "email is required"} 401 Unauthorized 認証されていない トークン未送信 トークン無効 注意： 認証失敗 = 401 認可失敗ではない 403 Forbidden 認証済みだが権限がない ロール不足 自分以外のリソースにアクセス 401と混同しやすいので要注意。 404 Not Found リソースが存在しない IDが存在しない 存在を隠したい場合にも使われる（セキュリティ上） 実務では： 権限がない場合も404を返す設計も多い 409 Conflict 状態の衝突 一意制約違反 楽観ロック失敗 既に存在するリソース作成 POST /users (email重複)→ 409 Conflict REST的に非常に重要。 422 Unprocessable Entity 形式は正しいが意味的に不正 バリデーションエラー 業務ルール違反 例： パスワードが短い 年齢が規定外 400との使い分け： 構文 → 400 意味 → 422 429 Too Many Requests レート制限 API制限超過 Retry-Afterヘッダと併用 5. 5xx（サーバ側エラー） 500 Internal Server Error 想定外の例外 バグ 想定漏れ クライアントに詳細は返さない。 502 Bad Gateway 依存サービスの異常 外部API失敗 マイクロサービス間通信エラー 503 Service Unavailable 一時的に使えない メンテナンス 高負荷 Retry-Afterを返すのが望ましい。 504 Gateway Timeout 依存先がタイムアウト DB応答なし 外部API遅延 6. よくある設計ミス ① 何でも200で返す エラーをbodyで表現 クライアント側が地獄 → HTTPの意味を使うべき ② 400と422を区別しない バリデーションエラーが曖昧 ③ 401と403の混同 セキュリティ事故の原因になりやすい 7. 実務でよく使う最小セット 現実的には、まずこれを押さえれば十分です。 200 OK201 Created204 No Content400 Bad Request401 Unauthorized403 Forbidden404 Not Found409 Conflict422 Unprocessable Entity429 Too Many Requests500 Internal Server Error503 Service Unavailable 8. 設計の基本思想（重要） REST APIのステータスコードは、 「HTTPレイヤで何が起きたか」 をクライアントに伝える契約 です。 業務エラーを全部200に押し込めると クライアントが判断できなくなる APIが使いにくくなる まとめ（一言） 2xx：成功の「種類」を表す 4xx：クライアントが直すべき問題 5xx：API側が直すべき問題 REST API設計では、 ステータスコードは「仕様の一部」であり、 実装者の好みではない という意識が重要です。

マスタリングAPIアーキテクチャ モノリシックからマイクロサービスへとアーキテクチャを進化させるための実践的手法 [ James Gough ] 価格:3740円 (2026/1/28 18:00時点) 感想(0件)

にほんブログ村