エラーの返し方を決めていない API は、呼ぶ側が「とりあえず全部やり直す」しかなくなります。
成功したときの形は、たいてい最初に決めます。決め忘れるのは失敗したときの形です。ある失敗は 200 で {"error":"..."}、別の失敗は 500 で HTML、また別のは何も返らずタイムアウト。呼ぶ側から見ると、同じ「失敗」なのに毎回違う形が飛んできます。
この記事では、前の回で作った API にエラーの型を1つ決めて通し、呼ぶ側が「やり直してよいか」を判断できる状態にします。作るのは大きな仕組みではなく、返す形を1つに揃えることと、コードの選び方の基準です。
対象レベル: 初級〜中級 / 区分: 必修
この記事でわかること
- 4xx と 5xx の分かれ目は「呼ぶ側が直せるかどうか」だということ
- 同じ「見つからない」でも
404と200で空配列を分ける基準 - エラーの本文に何を入れて、何を入れてはいけないか
- やり直してよい失敗と、やり直してはいけない失敗の区別の伝え方
- 例外を握りつぶすと、なぜ調査ができなくなるか
この記事でやること
- いまの API が、失敗したときに何を返しているかを実際に叩いて確かめる
- エラーの形を1つの型に決める
- 入力の誤り・見つからない・こちらの落ち度を打ち分ける
- わざと落として、利用者には短く、ログには詳しくを確かめる
先に知る言葉
この記事で初めて出てくる言葉です。 詳しくは用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| 4xx / 5xx | 送った側の問題か、受けた側の問題かの区別 |
| エラーコード | 呼ぶ側が分岐に使う短い識別子。 文言とは別に持つ |
| requestId | 1 回の処理に振る番号。返す本文とログを突き合わせるために使う |
| 例外 | 処理を続けられないときに投げられるもの。握りつぶすと調査ができなくなる |
| 冪等(べきとう) | 何回やっても結果が同じこと。再試行してよいかの判断に効く |
前提と作業場所
VM の中(Ubuntu Server)で打ちます。 前の回で作った ~/server の Node.js の API がある前提です。無い場合は、REST API を作る回に戻ってください。
この記事ではデータベースは触りません。 変更するのは ~/server のコードだけで、作業前にコピーを取ります。
戻したくなったら、このフォルダから書き戻せます。
いま何を返しているか、先に見る
存在しない ID を取りに行きます。
ここで返ってくるのが 200 なら、失敗を成功として返しています。500 なら、想定していない落ち方をしています。どちらも、呼ぶ側は困ります。
本文も見ます。
HTML が返ってきたら要注意です。 JSON を期待している呼び出し側は、それを解析しようとして別のエラーで落ちます。「エラーの中で、さらにエラーが起きる」のはこの形です。
4xx と 5xx の分かれ目
迷ったときの基準は1つです。
呼ぶ側が、送る内容を変えれば成功できるか。 できるなら 4xx、できないなら 5xx。
| 状況 | コード | 理由 |
|---|---|---|
| 必須の項目が無い・型が違う | 400 | 直して送り直せば成功する |
| ログインしていない | 401 | 資格情報を付ければ成功する |
| ログイン済みだが権限が無い | 403 | 送り直しても成功しないが、原因は呼ぶ側にある |
| その ID のものが無い | 404 | URL を直せば成功する |
| すでに同じものがある | 409 | 別の内容にすれば成功する |
| DB に繋がらない・想定外の例外 | 500 | 呼ぶ側には何もできない |
401 と 403 の違いは頻出です。 401 は「あなたが誰か分からない」、403 は「あなたが誰かは分かった。その上で駄目」。ログイン画面へ飛ばしてよいのは 401 だけで、403 で飛ばすと、ログインし直しても同じところに戻ってきます。
404 にすべきか、空で返すべきか
ここは分かれます。基準は「1件を指しているか、集合を指しているか」です。
| URL | 該当が無いとき | 理由 |
|---|---|---|
/api/tasks/42 | 404 | 42 番という特定の物を指したのに、無い |
/api/tasks?done=true | 200 と [] | 条件に合う集合を聞いた。0 件は正しい答え |
「検索結果が 0 件」で 404 を返すと、呼ぶ側は「URL を間違えた」と読みます。 空配列は失敗ではありません。
エラーの形を1つに決める
返す形を決めます。成功と同じく JSON で、必ず同じキーを持たせます。
{
"error": {
"code": "task_not_found",
"message": "指定されたタスクが見つかりません",
"requestId": "b3f1c9"
}
}
| キー | 用途 | 読む相手 |
|---|---|---|
code | プログラムが分岐に使う短い識別子。変えない | 呼ぶ側のコード |
message | 画面に出せる説明。変わってよい | 人 |
requestId | ログと突き合わせるための番号 | 調べる人 |
message で分岐してはいけません。 文言はいつか変わります。表記を直しただけで呼ぶ側が壊れるのは、この設計をしていないときです。分岐は code でやります。
入れてはいけないもの
例外の内容をそのまま返さないでください。 次のようなものが含まれます。
- ファイルのパスとソースの行番号(どこに何を置いているかが分かる)
- SQL 文とテーブル名・列名(構造がそのまま分かる)
- 接続先のホスト名・利用者名
これらは攻撃する側にとって、地図そのものです。 一方で、調べるときには必要です。だから置き場所を分けます。
利用者に返すのは短く、ログには詳しく。 突き合わせるのが
requestId。
実装する
ファイルを開きます。
エラーを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(...) を書くと、必ず揃わなくなります。
// 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 にまとめることで、書き忘れが安全側に倒れます。
組み込みます。ルートを全部書いたあと、いちばん最後に置きます。
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 の中で何もしないのが、いちばん調査を難しくします。
打ち分けを確かめる
3通り叩きます。
{"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 を出す
存在しない関数を呼んでみます。
返る本文には internal_error と requestId しかありません。スタックトレースは1文字も出ていません。
調べる側は、その番号でログを引きます。
利用者に見せない情報が、ログには残っている。これが分けた理由です。
つまずいたところ
例外を catch して console.log だけして、何も返しませんでした。 画面はずっと読み込み中のままで、サーバーのログにも1行しか出ず、再現に半日かかりました。catch したら必ず「返す」か「渡す」のどちらかをします。
エラーの文言で分岐していました。 「見つかりません」を「存在しません」に直しただけで、呼ぶ側の分岐が全部外れました。code を足していれば起きませんでした。
検索の 0 件を 404 で返していました。 呼ぶ側が「URL が違う」と判断して再試行を止め、絞り込みが常に空に見える不具合になりました。集合を聞かれたら、0 件は 200 です。
後片づけ
作ったバックアップが要らなければ消します。書き戻したい場合は、消す前に cp -r ~/server-backup-before-errors/. ~/server/ で戻せます。
データベースには何もしていません。 変更したのは ~/server の中のファイルだけです。
まとめ
- 4xx と 5xx の分かれ目は「呼ぶ側が直せるか」。迷ったらこれで決める
- 1件を指して無ければ
404、集合を聞かれて 0 件なら200と空配列 - 失敗の形は1つに揃え、
codeで分岐させる。文言で分岐させない - 利用者に返すのは短く、ログには詳しく。 突き合わせは
requestId catchしたら必ず返すか渡す。握りつぶすと調査ができなくなる
参考リンク
次に読む
この記事は 【第5段階】バックエンドとデータベース の 7 / 29 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。

コメント