YoukaRequestError,以及用于以非成功状态结束的异步任务的 YoukaTaskError。两者都继承自 Error,并携带结构化字段,便于你根据 code、status 和是否可重试进行分支处理。
YoukaRequestError
在发生 HTTP 错误、请求校验失败或响应格式不正确时抛出。
字段
string
机器可读的错误码,例如
INVALID_REQUEST、UNAUTHORIZED、UPLOAD_FAILED。string
面向人的错误描述。
number
HTTP 状态码(如果可用)。
boolean
当 SDK 认为该错误值得重试时为
true(例如触发限流、短暂的服务器错误、幂等重放仍在进行中)。unknown
由服务器提供的详情;对于校验错误,通常是 Zod 的 issue 列表。
常见 code
YoukaTaskError
当底层 task 或 export 以 failed、cancelled 或 timed-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。请显式检查它:
下一步
- Tasks — wait 辅助方法与高级任务轮询
- Authentication — 构造函数选项与 signals
- API errors — 原始 HTTP 中的相同 code
