一貫したエラーレスポンスをどう設計し、validation エラーをどう報告しますか?

Question

IT Interview Practice · Accepted Answer

良いエラーレスポンスは 2 つのことをします: **正しい HTTP status code** (機械可読なシグナル) を使い、開発者が対処できる **一貫した構造化された body** を返します。一貫しないエラーの形は、client 側の苦痛の最大の源の 1 つです。

## 標準エラー形式を使う: RFC 7807 (problem+json)

RFC 7807 は専用のメディアタイプを持つ標準の「problem details」body を定義し、API 全体のすべてのエラーが同じ見た目になります:

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — エラーカテゴリを識別する URI (ドキュメントへ参照解決可能)。
- `title` — 短い人間可読な要約 (`type` ごとに安定)。
- `status` — HTTP status、便宜のためにミラーされる。
- `detail` — *この* 発生に固有の説明。
- `instance` — どのリクエスト/リソースで起きたか。

## Validation エラー: 一度にすべて報告する

フォーム/フィールドの検証には `422` (または `400`) と **フィールドエラーの配列** を返し、client がすべての不正なフィールドを一度にハイライトできるようにします — 一度に 1 つずつではなく:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## 原則

```text
✓ すべてのエラーで同じ body の形 (client 側で 1 つのコードパス)
✓ 安定した機械可読な code (type/code) — client はこれで分岐し、文章では分岐しない
✓ 開発者/ログ向けの人間可読な message
✗ stack trace、SQL、内部パスを client に決して漏らさない
```

## なぜ重要なのか

エラー設計は、API が現実世界で静かに成功するか失敗するかの場所です: ハッピーパスは簡単ですが、消費者はデバッグ時間の大半をエラーパスで費やし、一貫しない、あるいは曖昧なエラー契約は統合を惨めにします。面接官はこれで 2 つを確認します。第一に、**status code と構造化された body が連携すること** — status はツールと retry のための粗いシグナル、body は実行可能な詳細を運ぶ — であり、中にエラーを入れた `200 OK` というアンチパターンではないこと。第二に、**安定した機械可読なエラーコード** (RFC 7807 の `type` または `code` フィールド経由) で、client が、言い換えられたり localize されたりするかもしれない英語のメッセージを文字列一致するのでなく、`"insufficient_funds"` で分岐できること。validation エラーを一度にすべて返し、stack trace のような内部詳細を決して漏らさないことが、他のチームが実際に消費しなければならなかった API を作った証となる答えを完成させます。

標準エラー形式を使う: RFC 7807 (problem+json)

Validation エラー: 一度にすべて報告する

原則

なぜ重要なのか

関連する質問