code 是稳定的,请据此分支。message 面向人类阅读,可能变化。有补充信息时会附带 details:校验错误通常是 { field, message } 数组,其他情况可能是 { "id": "..." } 或 { "retryAfterSec": 5, "retryable": true } 这样的对象。
已被接受、之后才失败的任务不会产生 HTTP 错误,而是报告任务失败码。
请求错误码
请优先使用
error.code 而不是状态码:VALIDATION_ERROR 会以 400 和 422 两种状态出现。429 表示达到了你自己的限制,503 表示服务器容量暂时不足。
Retry-After
在POST /v1/async/task、POST /v1/async/task/batch 和 POST /v1/async/task/grid 上,每个 429 和 503 都带有以秒为单位的 Retry-After 请求头。其中大多数错误码还带有 details.retryAfterSec 和 details.retryable: true。边缘层请求限制返回的 429 两者都不带。参见积分与限制。
请求体大小上限
地区拒绝
REGION_UNSUPPORTED 在任务入队前就已判定,因此你会立即得知,而不必等任务失败:
批次与网格的逐项错误
在POST /v1/async/task/batch 上,即使有项目失败,格式正确的请求也会返回 200。状态码描述请求本身,results[].success 描述每个任务;失败的项目带有与请求错误相同的 { code, message, details, timestamp } 对象:
QUEUE_BACKPRESSURE 或 SERVER_OVERLOADED 失败的项目会在 details.retryAfterSec 中给出等待时间。只有整个批次被拒绝时,请求本身才会以 400、413、429 或 503 失败。
POST /v1/async/task/grid 以同样方式在 points[] 中报告被拒的点位。POST /v1/batches 在任一项目无效时以 400 拒绝整个批次,并把准入拒绝的项目(例如 INSUFFICIENT_CREDITS)保存为 REJECTED。idempotencyKey 与批次之前创建的任务匹配的项目,在该任务不再保留后显示为带 TASK_NOT_RETAINED 的 FAILED。参见批次与网格。
任务失败码
入队后失败的任务以FAILED 结束。轮询返回顶层 error 字符串,而不是请求错误对象:
response.error 中携带相同的字符串。字符串以错误码开头,请据此分支。