API エラーハンドリング

目次

• 概要
• いつ使うか
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

標準化されたエラーレスポンス、詳細なログ記録、エラー分類、ユーザーフレンドリーなエラーメッセージを備えた堅牢なエラーハンドリングシステムを構築します。このスキルは、型付きエラーのスロー、ログ記録、監視、クライアント向けレスポンスフォーマットのライフサイクル全体をカバーしています。

いつ使うか

• エンドポイント全体でAPIエラーを一貫して処理する
• リクエストトレーシングで本番環境の問題をデバッグする
• エラー回復戦略（リトライ、サーキットブレーカー）を実装する
• エラーレートを監視してアラート設定する
• クライアントに意味のある、実行可能なエラーメッセージを提供する
• リクエスト入力を処理前に検証する
• 時系列でエラーパターンを追跡する

クイックスタート

最小限の標準化されたエラーレスポンスフォーマット:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "statusCode": 422,
    "requestId": "req_abc123xyz789",
    "timestamp": "2025-01-15T10:30:00Z",
    "details": [
      { "field": "email", "message": "Invalid email format", "code": "INVALID_EMAIL" }
    ]
  }
}

カスタムエラークラス (Node.js):

class ApiError extends Error {
  constructor(code, message, statusCode = null, details = null) {
    super(message);
    this.code = code;
    this.statusCode = statusCode || ERROR_CODES[code]?.status || 500;
    this.details = details;
    this.timestamp = new Date().toISOString();
  }
}

// 使用例
throw new ApiError("NOT_FOUND", "User not found", 404);
throw new ApiError("VALIDATION_ERROR", "Missing fields", 422, fieldErrors);

リファレンスガイド

references/ ディレクトリ内の詳細実装:

ガイド	内容
エラーコード & レスポンスフォーマット	完全な ERROR_CODES マップ、レスポンスフォーマッター、グローバルミドルウェア (Node.js + Python)
リトライ戦略 & サーキットブレーカー	指数バックオフ、ジッター、サーキットブレーカーパターン
監視 & トラッキング	Sentry統合、エラーレートメトリクス、/metrics/errors エンドポイント
検証パターン	入力検証、スキーマガード、エラーが発生する前に不正なレスポンスを検出する

ベストプラクティス

✅ すべき事

• すべてのエンドポイント全体で一貫したエラーレスポンスフォーマットを使用する
• 観測可能性のため、すべてのエラーに requestId と traceId を含める
• 5xxエラーは ERROR レベルでログ、4xxは WARN レベルでログ
• 実行可能なエラーメッセージを提供する — クライアントに何を修正するかを伝える
• 標準的なHTTPステータスコード (4xxクライアントエラー、5xxサーバーエラー) を使用する
• 一時的な失敗に対して指数バックオフでリトライを実装する
• サーキットブレーカーを使用してカスケード障害を防ぐ
• 入力を早期に検証し、すべてのフィールドエラーを一度に返す
• エラーレートを監視し、異常なスパイクでアラート設定する

❌ してはいけない事

• スタックトレースや内部実装の詳細をクライアントに公開する
• エラーレスポンスにHTTP 200を返す
• エラーを黙って飲み込む
• センシティブデータ（パスワード、トークン、個人情報）をログに記録する
• 「何か問題が発生しました」のような曖昧なメッセージを使用する
• エラーハンドリングロジックとビジネスロジックを混在させる
• 非べき等操作またはクライアントエラー (4xx) をリトライする
• 異なるエンドポイントから異なるエラー形式を返す