APIのエラー設計 — 4xxと5xxの分け方と、返す本文の決め方

APIのエラー設計。4xxと5xxの応答カード、パソコンとサーバー。

エラーの返し方を決めていない API は、呼ぶ側が「とりあえず全部やり直す」しかなくなります。

成功したときの形は、たいてい最初に決めます。決め忘れるのは失敗したときの形です。ある失敗は 200 で {"error":"..."}、別の失敗は 500 で HTML、また別のは何も返らずタイムアウト。呼ぶ側から見ると、同じ「失敗」なのに毎回違う形が飛んできます。

この記事では、前の回で作った API にエラーの型を1つ決めて通し、呼ぶ側が「やり直してよいか」を判断できる状態にします。作るのは大きな仕組みではなく、返す形を1つに揃えることと、コードの選び方の基準です。

対象レベル: 初級〜中級 / 区分: 必修

目次

この記事でわかること

  • 4xx と 5xx の分かれ目は「呼ぶ側が直せるかどうか」だということ
  • 同じ「見つからない」でも 404 と 200 で空配列を分ける基準
  • エラーの本文に何を入れて、何を入れてはいけないか
  • やり直してよい失敗と、やり直してはいけない失敗の区別の伝え方
  • 例外を握りつぶすと、なぜ調査ができなくなるか

この記事でやること

  1. いまの API が、失敗したときに何を返しているかを実際に叩いて確かめる
  2. エラーの形を1つの型に決める
  3. 入力の誤り・見つからない・こちらの落ち度を打ち分ける
  4. わざと落として、利用者には短く、ログには詳しくを確かめる

先に知る言葉

この記事で初めて出てくる言葉です。 詳しくは用語集にもまとめてあります。

言葉意味
4xx / 5xx送った側の問題か、受けた側の問題かの区別
エラーコード呼ぶ側が分岐に使う短い識別子。 文言とは別に持つ
requestId1 回の処理に振る番号。返す本文とログを突き合わせるために使う
例外処理を続けられないときに投げられるもの。握りつぶすと調査ができなくなる
冪等(べきとう)何回やっても結果が同じこと。再試行してよいかの判断に効く

前提と作業場所

VM の中(Ubuntu Server)で打ちます。 前の回で作った ~/server の Node.js の API がある前提です。無い場合は、REST API を作る回に戻ってください。

この記事ではデータベースは触りません。 変更するのは ~/server のコードだけで、作業前にコピーを取ります。

bash
$ cd ~/server
$ cp -r . ~/server-backup-before-errors
$ ls ~/server-backup-before-errors

戻したくなったら、このフォルダから書き戻せます。

いま何を返しているか、先に見る

存在しない ID を取りに行きます。

bash
$ curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/tasks/999999

ここで返ってくるのが 200 なら、失敗を成功として返しています。500 なら、想定していない落ち方をしています。どちらも、呼ぶ側は困ります。

本文も見ます。

bash
$ curl -s http://localhost:3000/api/tasks/999999

HTML が返ってきたら要注意です。 JSON を期待している呼び出し側は、それを解析しようとして別のエラーで落ちます。「エラーの中で、さらにエラーが起きる」のはこの形です。

4xx と 5xx の分かれ目

迷ったときの基準は1つです。

呼ぶ側が、送る内容を変えれば成功できるか。 できるなら 4xx、できないなら 5xx。

状況コード理由
必須の項目が無い・型が違う400直して送り直せば成功する
ログインしていない401資格情報を付ければ成功する
ログイン済みだが権限が無い403送り直しても成功しないが、原因は呼ぶ側にある
その ID のものが無い404URL を直せば成功する
すでに同じものがある409別の内容にすれば成功する
DB に繋がらない・想定外の例外500呼ぶ側には何もできない

401 と 403 の違いは頻出です。 401 は「あなたが誰か分からない」、403 は「あなたが誰かは分かった。その上で駄目」。ログイン画面へ飛ばしてよいのは 401 だけで、403 で飛ばすと、ログインし直しても同じところに戻ってきます。

404 にすべきか、空で返すべきか

ここは分かれます。基準は「1件を指しているか、集合を指しているか」です。

URL該当が無いとき理由
/api/tasks/4240442 番という特定の物を指したのに、無い
/api/tasks?done=true200 と []条件に合う集合を聞いた。0 件は正しい答え

「検索結果が 0 件」で 404 を返すと、呼ぶ側は「URL を間違えた」と読みます。 空配列は失敗ではありません。

エラーの形を1つに決める

返す形を決めます。成功と同じく JSON で、必ず同じキーを持たせます。

{
  "error": {
    "code": "task_not_found",
    "message": "指定されたタスクが見つかりません",
    "requestId": "b3f1c9"
  }
}
キー用途読む相手
codeプログラムが分岐に使う短い識別子。変えない呼ぶ側のコード
message画面に出せる説明。変わってよい人
requestIdログと突き合わせるための番号調べる人

message で分岐してはいけません。 文言はいつか変わります。表記を直しただけで呼ぶ側が壊れるのは、この設計をしていないときです。分岐は code でやります。

入れてはいけないもの

例外の内容をそのまま返さないでください。 次のようなものが含まれます。

  • ファイルのパスとソースの行番号(どこに何を置いているかが分かる)
  • SQL 文とテーブル名・列名(構造がそのまま分かる)
  • 接続先のホスト名・利用者名

これらは攻撃する側にとって、地図そのものです。 一方で、調べるときには必要です。だから置き場所を分けます。

利用者に返すのは短く、ログには詳しく。 突き合わせるのが requestId。

実装する

ファイルを開きます。

bash
$ nano ~/server/errors.js

エラーを1か所で作る小さな部品を書きます。

// errors.js — エラーの形を1つに揃える
export class ApiError extends Error {
  constructor(status, code, message) {
    super(message);
    this.status = status;   // HTTP のコード
    this.code = code;       // 呼ぶ側が分岐に使う識別子
  }
}

export const notFound = (what) =>
  new ApiError(404, `${what}_not_found`, `指定された${what}が見つかりません`);

export const badRequest = (msg) =>
  new ApiError(400, "invalid_request", msg);

次に、返すところを1か所にまとめます。各所で res.status(...) を書くと、必ず揃わなくなります。

bash
$ nano ~/server/error-handler.js
// error-handler.js — 最後にここを通す
import { randomUUID } from "node:crypto";
import { ApiError } from "./errors.js";

export function errorHandler(err, req, res, next) {
  const requestId = randomUUID().slice(0, 6);

  if (err instanceof ApiError) {
    // 想定した失敗。ログは1行でよい
    console.warn(`[${requestId}] ${err.status} ${err.code} ${req.method} ${req.url}`);
    return res.status(err.status).json({
      error: { code: err.code, message: err.message, requestId }
    });
  }

  // 想定していない失敗。ログには全部、返すのは最小限
  console.error(`[${requestId}] 500 ${req.method} ${req.url}`, err);
  return res.status(500).json({
    error: {
      code: "internal_error",
      message: "処理に失敗しました。時間をおいて試してください",
      requestId
    }
  });
}

2つの分岐しかありません。 「自分で投げた想定内のもの」と「それ以外」です。それ以外を 500 にまとめることで、書き忘れが安全側に倒れます。

組み込みます。ルートを全部書いたあと、いちばん最後に置きます。

bash
$ nano ~/server/index.js
import { errorHandler } from "./error-handler.js";
import { notFound, badRequest } from "./errors.js";

app.get("/api/tasks/:id", async (req, res, next) => {
  try {
    if (req.query.boom) notDefinedFunction();   // ?boom=1 のときだけ、存在しない関数を呼ぶ(わざと 500 を出す練習用)
    const id = Number(req.params.id);
    if (!Number.isInteger(id)) throw badRequest("id は整数で指定してください");
    const task = await findTask(id);
    if (!task) throw notFound("タスク");
    res.json(task);
  } catch (e) {
    next(e);          // ここで握りつぶさない
  }
});

app.use(errorHandler); // 必ず最後

next(e) を書き忘れると、応答が返らないまま止まります。 呼ぶ側からはタイムアウトに見え、原因がまったく分かりません。catch の中で何もしないのが、いちばん調査を難しくします。

打ち分けを確かめる

bash
$ cd ~/server
$ node index.js > server.log 2>&1 &     # ログを ~/server/server.log に書き出す
$ sleep 1

3通り叩きます。

bash
$ curl -s -w " [%{http_code}]\n" http://localhost:3000/api/tasks/abc
$ curl -s -w " [%{http_code}]\n" http://localhost:3000/api/tasks/999999
$ curl -s -w " [%{http_code}]\n" http://localhost:3000/api/tasks/1
{"error":{"code":"invalid_request","message":"id は整数で指定してください","requestId":"a1b2c3"}} [400]
{"error":{"code":"タスク_not_found","message":"指定されたタスクが見つかりません","requestId":"d4e5f6"}} [404]
{"id":1,"title":"買い物","done":false} [200]

3つとも JSON で、失敗の形が同じになりました。呼ぶ側はこう書けます。

const res = await fetch(url);
if (!res.ok) {
  const body = await res.json();
  if (body.error.code === "invalid_request") { /* 入力を直させる */ }
  else if (res.status >= 500)               { /* あとで再試行 */ }
  else                                       { /* 再試行しない */ }
}

ここが目的でした。 「やり直してよいか」が、コードを見るだけで決まります。

なお、上の code に日本語が混ざっています。notFound("タスク") の引数をそのまま使ったためです。code は英字にしてください。

export const notFound = (what, label) =>
  new ApiError(404, `${what}_not_found`, `指定された${label}が見つかりません`);

呼ぶときは notFound("task", "タスク") です。プログラムが読む物と、人が読む物を混ぜないという、この記事の話がそのまま出た例です。

わざと 500 を出す

存在しない関数を呼んでみます。

bash
$ curl -s -w " [%{http_code}]\n" "http://localhost:3000/api/tasks/1?boom=1"

返る本文には internal_error と requestId しかありません。スタックトレースは1文字も出ていません。

調べる側は、その番号でログを引きます。

bash
$ grep "a1b2c3" ~/server/server.log    # a1b2c3 は、返ってきた requestId に読み替える

利用者に見せない情報が、ログには残っている。これが分けた理由です。

つまずいたところ

例外を catch して console.log だけして、何も返しませんでした。 画面はずっと読み込み中のままで、サーバーのログにも1行しか出ず、再現に半日かかりました。catch したら必ず「返す」か「渡す」のどちらかをします。

エラーの文言で分岐していました。 「見つかりません」を「存在しません」に直しただけで、呼ぶ側の分岐が全部外れました。code を足していれば起きませんでした。

検索の 0 件を 404 で返していました。 呼ぶ側が「URL が違う」と判断して再試行を止め、絞り込みが常に空に見える不具合になりました。集合を聞かれたら、0 件は 200 です。

後片づけ

bash
$ jobs
$ kill %1 2>/dev/null
$ rm -rf ~/server-backup-before-errors

作ったバックアップが要らなければ消します。書き戻したい場合は、消す前に cp -r ~/server-backup-before-errors/. ~/server/ で戻せます。

データベースには何もしていません。 変更したのは ~/server の中のファイルだけです。

まとめ

  • 4xx と 5xx の分かれ目は「呼ぶ側が直せるか」。迷ったらこれで決める
  • 1件を指して無ければ 404、集合を聞かれて 0 件なら 200 と空配列
  • 失敗の形は1つに揃え、code で分岐させる。文言で分岐させない
  • 利用者に返すのは短く、ログには詳しく。 突き合わせは requestId
  • catch したら必ず返すか渡す。握りつぶすと調査ができなくなる

参考リンク

次に読む

この記事は 【第5段階】バックエンドとデータベース の 7 / 29 本目です。

記事
← 前の記事URLに動詞を入れない — REST APIの設計
→ 次の記事アプリのログ出力 — レベルの決め方とリクエストIDで1件を追う

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次