- エラーコード管理は「障害を分類し、原因特定を高速化し、運用を安定させるための必須技術」
- エラーコード管理の目的は「エラーを分類し、原因特定を高速化すること」
- ステップ1：エラーコードの命名規則を決める（最重要）
- ステップ2：エラーコード一覧を作る（辞書化）
- ステップ3：エラーコード付きの Error を作る
- ステップ4：エラーコードを含めて整形する
- ステップ5：共通 Logger にエラーコードを流す
- ステップ6：try/catch と組み合わせて使う（業務で必須）
- ステップ7：業務で使えるエラーコード管理ユーティリティ（完成版）
- ステップ8：業務での活用例
- 深掘り：エラーコード管理が重要な理由
- まとめ：エラーコード管理は「業務システムの品質を支える基盤技術」
エラーコード管理は「障害を分類し、原因特定を高速化し、運用を安定させるための必須技術」
業務システムでは、エラーは必ず発生します。 しかし、初心者が陥りやすい問題があります。
- エラーメッセージがバラバラで原因が分かりにくい
- ログを見ても「どの種類のエラーか」判断できない
- API・DB・外部サービスなどのエラーが混在して混乱する
- 同じエラーなのに毎回違うメッセージが出る
- 監視ツールで分類できない
これを解決するのが エラーコード管理 です。
エラーコードは、 「エラーを分類するための共通言語」 として機能します。
ここでは、初心者でも理解しやすいように、 エラーコード管理の考え方 → 設計 → 実装 → 業務テンプレート までをステップバイステップで丁寧に解説します。
エラーコード管理の目的は「エラーを分類し、原因特定を高速化すること」
エラーコードがないと起きる問題
- ログが読みにくい
- 同じエラーなのに表現がバラバラ
- 監視ツールで分類できない
- 運用担当者が原因を特定できない
- 障害対応が遅れる
エラーコードがあるとどうなる？
- エラーの種類が一目で分かる
- ログが統一される
- 監視ツールで分類しやすい
- 障害対応が高速化する
- チーム全体で共通言語ができる
ステップ1：エラーコードの命名規則を決める（最重要）
業務では、エラーコードは次のように分類します。
<カテゴリ>-<番号>
例：
| カテゴリ | 意味 |
|---|---|
| API | API 呼び出しのエラー |
| DB | データベースのエラー |
| AUTH | 認証・認可のエラー |
| VALID | バリデーションエラー |
| SYS | システム内部のエラー |
番号は 001, 002, 003… と連番にします。
例：
API-001：APIレスポンス不正DB-002：DB接続タイムアウトAUTH-003：トークン期限切れVALID-004：入力値が不正SYS-005：予期しない例外
ステップ2：エラーコード一覧を作る（辞書化）
export const ErrorCodes = {
API_INVALID_RESPONSE: "API-001",
API_TIMEOUT: "API-002",
DB_CONNECTION_FAILED: "DB-001",
DB_QUERY_FAILED: "DB-002",
AUTH_TOKEN_EXPIRED: "AUTH-001",
AUTH_UNAUTHORIZED: "AUTH-002",
VALID_REQUIRED: "VALID-001",
VALID_FORMAT_ERROR: "VALID-002",
SYS_UNKNOWN: "SYS-001",
};
ステップ3：エラーコード付きの Error を作る
class AppError extends Error {
constructor(code, message, extra = {}) {
super(message);
this.code = code;
Object.assign(this, extra);
}
}
使用例
throw new AppError(ErrorCodes.API_TIMEOUT, "APIがタイムアウトしました");
ステップ4：エラーコードを含めて整形する
function formatError(error) {
return {
code: error.code || "SYS-001",
name: error.name,
message: error.message,
stack: error.stack,
...Object.keys(error).reduce((acc, key) => {
acc[key] = error[key];
return acc;
}, {}),
};
}
ステップ5：共通 Logger にエラーコードを流す
function logError(error, context = "") {
Logger.error(formatError(error), context);
}
ステップ6：try/catch と組み合わせて使う（業務で必須）
try {
await fetch("/api/user");
} catch (e) {
const err = new AppError(ErrorCodes.API_INVALID_RESPONSE, "APIレスポンスが不正です", { original: e });
logError(err, "UserAPI");
}
ステップ7：業務で使えるエラーコード管理ユーティリティ（完成版）
export const ErrorCodes = {
API_INVALID_RESPONSE: "API-001",
API_TIMEOUT: "API-002",
DB_CONNECTION_FAILED: "DB-001",
DB_QUERY_FAILED: "DB-002",
AUTH_TOKEN_EXPIRED: "AUTH-001",
AUTH_UNAUTHORIZED: "AUTH-002",
VALID_REQUIRED: "VALID-001",
VALID_FORMAT_ERROR: "VALID-002",
SYS_UNKNOWN: "SYS-001",
};
export class AppError extends Error {
constructor(code, message, extra = {}) {
super(message);
this.code = code;
Object.assign(this, extra);
}
}
export const ErrorUtil = {
format(error) {
return {
code: error.code || ErrorCodes.SYS_UNKNOWN,
name: error.name,
message: error.message,
stack: error.stack,
...Object.keys(error).reduce((acc, key) => {
acc[key] = error[key];
return acc;
}, {}),
};
},
log(error, context = "") {
Logger.error(this.format(error), context);
},
};
ステップ8：業務での活用例
API エラー
throw new AppError(ErrorCodes.API_TIMEOUT, "APIがタイムアウトしました");
DB エラー
throw new AppError(ErrorCodes.DB_CONNECTION_FAILED, "DB接続に失敗しました");
認証エラー
throw new AppError(ErrorCodes.AUTH_TOKEN_EXPIRED, "トークンの有効期限が切れています");
バリデーションエラー
throw new AppError(ErrorCodes.VALID_REQUIRED, "name は必須です");
深掘り：エラーコード管理が重要な理由
1. 障害調査が高速化する
ログを見れば「どの種類のエラーか」が一瞬で分かります。
2. 監視ツールで分類しやすい
Datadog、Sentry、CloudWatch などはコードで分類できます。
3. チーム全体で共通言語ができる
「API-001 が出てる」だけで状況が共有できます。
4. エラーメッセージが統一される
メッセージがバラバラになる問題を防げます。
5. 障害対応の属人化を防ぐ
誰が見ても理解できるログになります。
まとめ：エラーコード管理は「業務システムの品質を支える基盤技術」
エラーコード管理を正しく扱うことで、次のメリットが得られます。
- エラーの分類が明確になる
- 障害調査が高速化する
- ログ形式が統一される
- 監視ツールとの連携が容易になる
- チーム全体で共通言語ができる
エラーコードはただの文字列ではなく、 システムの健康状態を記録する重要な診断データ です。
ぜひ、業務システムにエラーコード管理を導入してください。