Models
Error
標準錯誤回應格式
錯誤回應結構
所有端點都用同一種 envelope 回傳錯誤。
{
"success": false,
"error": {
"code": "INVALID_URL",
"status": 400,
"message": "The provided URL is not valid",
"details": null
}
}欄位
success(boolean)：錯誤時恆為falseerror.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.* 欄位是穩定承諾。未來新增欄位會向後相容 —— 客戶端可以安全忽略未知欄位。