エラー設計 — 呼び出し側が正しく振る舞える情報を返す

What — ステータスコードが伝えていること

HTTP ステータスコードの百の位は、誰が何をすべきかを表しています。

よく使うコードの使い分け

400 Bad Request

リクエストの形式が不正。JSON がパースできない、必須項目がない。

401 Unauthorized

認証されていない。ログインすれば通る可能性がある。名前に反して「認証」の話。

403 Forbidden

認証済みだが権限がない。ログインし直しても通らない。

404 Not Found

リソースが存在しない。存在を隠したい場合、403 の代わりに使うこともある。

409 Conflict

現在の状態と矛盾する。すでにキャンセル済みの注文をキャンセルしようとした、など。

422 Unprocessable Entity

形式は正しいが内容が業務ルールに反する。メールアドレスの形式は正しいが既に使われている、など。

429 Too Many Requests

レート制限。4xx だが、待てば通る。Retry-After ヘッダで待ち時間を伝える。

503 Service Unavailable

一時的に利用できない。メンテナンス中や過負荷。Retry-After を付けられる。

エラーレスポンスの本体に何を入れるか

HTTP 200 OK
{
"success": false,
"message": "エラーが発生しました"
}

クライアントにできること:
- メッセージをそのまま画面に出す
- 文字列で分岐する（サーバーの文言変更で壊れる）
- リトライすべきか判断できない

Why — エラーは「次に何をすべきか」の指示

呼び出し側がエラーを受け取ったとき、判断すべきことは3つです。

1. リトライしてよいか — 一時的な問題か、直さないと通らないか
2. 何を直せばよいか — どのフィールドの、どういう問題か
3. 利用者に何を伝えるか — そのまま表示してよい文言か

この3つに答えられないエラーレスポンスは、呼び出し側に「とりあえず何か失敗した」としか伝えていません。

なぜ 200 で返してはいけないのか

「HTTP は転送の成功、業務エラーはボディで」という考え方には一理あります。しかし実務では次のコストが発生します。

• 監視が機能しない。 エラー率、SLO、アラートがすべて HTTP ステータスを基準にしている
• ロードバランサやプロキシが異常を検知できない。 5xx が続けばインスタンスを切り離す、といった仕組みが働かない
• クライアントのライブラリが素直に使えない。 多くの HTTP クライアントは、ステータスで例外を投げるか否かを決める
• CDN やキャッシュが誤ってキャッシュする。 200 はキャッシュ可能と解釈されうる

HTTP のエコシステム全体がステータスコードを前提に動いているので、そこから外れると多くの仕組みが無効になります。

内部情報を漏らさない

エラーメッセージは攻撃の手がかりになります。

// 危険
{ "message": "SQLSTATE[42S02]: Base table 'prod_db.users' doesn't exist" }
{ "message": "ユーザー ID 12345 は存在しますが、パスワードが違います" }

// 安全
{ "code": "INTERNAL_ERROR", "message": "処理に失敗しました", "traceId": "01H8X..." }
{ "code": "INVALID_CREDENTIALS", "message": "メールアドレスまたはパスワードが正しくありません" }

• スタックトレースや SQL を返さない。 テーブル構造やフレームワークのバージョンが漏れる
• 認証では「どちらが間違っているか」を言わない。 メールアドレスの存在確認に使われる
• 代わりに traceId を返す。 詳細はサーバーのログにあり、問い合わせ時に突き合わせられる

リトライの作法

5xx を受け取ったクライアントは、リトライしてよい。ただしやり方が重要です。

// 悪い：全員が同じタイミングで殺到する
for (let i = 0; i < 3; i++) {
  try { return await call(); } catch { await sleep(1000); }
}

// 良い：指数バックオフ + ジッター
for (let i = 0; i < 3; i++) {
  try { return await call(); }
  catch (e) {
    if (!isRetryable(e)) throw e;          // 4xx はリトライしない
    const base = 2 ** i * 200;             // 200, 400, 800ms
    await sleep(base + Math.random() * base);  // ジッターで分散
  }
}

ジッター（ランダムなずれ）が重要です。 固定間隔だと、障害から復旧した瞬間に全クライアントが同時にリトライし、再び落ちます（サンダリングハード）。

演習 — まず自分で判断する

解説を読む前に、まず自分で判断してみてください。ここで一度詰まっておくと、 次の節の判断軸が「なるほど」ではなく「そう来たか」に変わります。