Skip to main content
SDK 提供两种错误类:用于 HTTP 与校验失败的 YoukaRequestError,以及用于以非成功状态结束的异步任务的 YoukaTaskError。两者都继承自 Error,并携带结构化字段,便于你根据 code、status 和是否可重试进行分支处理。

YoukaRequestError

在发生 HTTP 错误、请求校验失败或响应格式不正确时抛出。

字段

string
机器可读的错误码,例如 INVALID_REQUESTUNAUTHORIZEDUPLOAD_FAILED
string
面向人的错误描述。
number
HTTP 状态码(如果可用)。
boolean
当 SDK 认为该错误值得重试时为 true(例如触发限流、短暂的服务器错误、幂等重放仍在进行中)。
unknown
由服务器提供的详情;对于校验错误,通常是 Zod 的 issue 列表。

常见 code

YoukaTaskError

当底层 task 或 export 以 failedcancelledtimed-out 结束时,由 client.tasks.wait(...)client.projects.wait(...)client.exports.wait(...) 抛出。

字段

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'
直接映射到任务的终态状态。
string
服务器提供的任务错误信息,或生成的兜底信息。
TaskStatus
任务的终态状态。
RestTask
失败时刻的完整 task payload。适用于日志记录与面向用户的错误提示。

重试模式

retryable 与幂等键结合,构建一个安全的重试循环:
重试时务必复用同一个幂等键。否则服务器会将重试视为一次新请求,你可能会得到重复结果。

中止与取消

中止请求会抛出标准 AbortError —— 而不是 YoukaRequestError。请显式检查它:

下一步