Models
错误
标准错误响应格式
错误响应结构
所有端点都用这个统一的 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.* 字段是稳定承诺。未来新增字段会向后兼容 —— 客户端可以安全忽略未知字段。