api-error-handling

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();
  }
}

// Usage
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）をリトライする
• エンドポイントごとに異なる形式のエラーを返す