Skip to main content
所有失败共享同一个信封:
code 是稳定的,可放心用于分支判断。message 面向人类阅读,可能变化。能确定出错字段时会附带 details。

错误码

400 用于我们无法解析或理解的请求。422 专用于格式完全正确、但无法为所请求地区提供服务的请求。按 error.code 分支比按状态码分支更持久。

地区拒绝

两个地区错误码都在任务入队之前判定,你会立即得知,而不必看着任务耗尽重试预算后以一个表象错误失败。 REGION_UNSUPPORTED 是永久性的,该引擎无法服务所请求的国家:
请参阅无法服务的组合表。 REGION_UNAVAILABLE 是暂时性的:路径存在,但此刻没有可用资源。查询 GET /capacity 了解各地区当前能服务的范围。

批量失败按项计算

格式正确的批次始终返回 200,即使其中所有任务都失败。HTTP 状态描述的是请求;results[].success 描述每个任务。
只有整个请求格式错误时(非 JSON、不是数组、为空、超过 500 项、超过 8 MB 或未授权),批次本身才会返回 4xx。
批次项可能以 REGION_UNAVAILABLE 或 ENQUEUE_ERROR 失败,这两者都不在本 API 所实现的异步任务协议的单项错误 枚举中。它们是新增而非替换,VALIDATION_ERROR 和 RESOURCE_ALREADY_EXISTS 保持不变。

任务级失败

入队之后失败的任务完全不会产生 HTTP 错误。你会从终止状态得知:
注意结构差异:这里的顶层 error 是字符串,而不是请求级错误使用的 {code, message, timestamp} 对象。 它以错误码开头,后面跟着该错误码对应的固定说明,因此请按错误码分支:ENGINE_TIMEOUT、ENGINE_NO_RESULT、 ENGINE_FAILED,以及在规定时间内没有空出处理容量时的 NO_IP_AVAILABLE 和 NO_ACCOUNT_AVAILABLE(稍后重试通常可以成功)。 BAD_PAYLOAD 和 PAGE_UNAVAILABLE(无法匿名读取的 Naver 页面)会保留说明需要修改什么的消息。同一任务也会投递 task.status === "FAILED" 的 webhook。