Error

エラーレスポンスの形

すべてのエンドポイントは、この統一されたエンベロープでエラーを返します。

{
  "success": false,
  "error": {
    "code":    "INVALID_URL",
    "status":  400,
    "message": "The provided URL is not valid",
    "details": null
  }
}

フィールド

• success (boolean)：エラー時は常に false
• error.code (string)：機械可読のエラーコード — エラーコード を参照
• error.status (number)：HTTP ステータスコード（レスポンスステータスと一致。生のステータスを取得できない場合に有用）
• error.message (string)：人間可読のエラー説明
• error.details (object | null)：エラーの構造化コンテキスト — 例えば INVALID_PARAMETER では { field: message } のフィールド単位バリデーションエラーが返される；該当しない場合は null

TypeScript 型

type ErrorResponse = {
  success: false;
  error: {
    code: string;       // machine-readable, e.g. "INVALID_URL"
    status: number;     // HTTP status code
    message: string;    // human-readable
    details: Record<string, unknown> | null;
  };
};

安定した契約： 上記 4 つの error.* フィールドは保証されます。今後の追加は後方互換を保つため、クライアントは未知のフィールドを安全に無視できます。