文档目录

错误码

最近更新: 2026-10-22

未被受理的请求会返回非 2xx 状态码和 JSON 错误信息。被拒绝的请求不会创建任务,也不会扣费。

{
  "error": {
    "code": "insufficient_credits",
    "message": "There are not enough available credits."
  },
  "request_id": "5b0d2f4e-1c3a-4e6b-8d7f-9a0b1c2d3e4f"
}
字段类型说明
error.codestring稳定的机器可读错误码,请据此判断处理逻辑。
error.messagestring给人看的说明,内容可能调整。
request_idstring同时出现在 X-Request-Id 响应头中。联系支持时请附上。

错误码列表

HTTPerror.code含义与处理
400invalid_request请求体不是合法 JSON,含有未定义、为 null 或重复的字段,Content-Type 不是 application/json,或 Idempotency-Key 格式不对。请修正请求。
401invalid_api_keyAPI Key 缺失、格式错误或已撤销。
402insufficient_credits没有可用积分,请购买积分或套餐。
404prediction_not_found该账户下没有这个任务。
404not_found接口地址不存在。
409idempotency_conflict这个 Idempotency-Key 已用于不同的输入。新任务请使用新的 Key。
413request_too_large请求体超过 64 KiB。
422invalid_image_url图片 URL 不是可接受的公网 HTTPS 地址。
429inflight_limit_exceeded该账户已有 50 个任务在等待或处理中,待部分任务结束后再提交。
429rate_limited查询过于频繁,按 Retry-After 秒数等待后重试。
503temporarily_unavailable服务暂时不可用。对于提交请求,任务可能已受理也可能没有:请用相同的 Idempotency-Key 和输入重试。

任务已受理、之后才失败的情况不属于错误响应:任务的 status 会变为 "failed",原因写在任务的 error 中。见查询任务详情。

重试与幂等

超时、连接中断或 503 都可能让你无法确定提交是否已被受理。幂等键可以让重试变得安全。

  • 每张需要检测的图片使用一个唯一的 Idempotency-Key,并和你自己的业务记录保存在一起。
  • 用相同的 Key 和相同的输入(图片 URL 及其查询参数、模型、策略)重试,会返回原任务,状态码 200 OK,并带 Idempotent-Replayed: true。不会新建任务,也不会扣费,即使原任务已经失败或当前余额为零。
  • 相同的 Key 配不同的输入,返回 409 idempotency_conflict。
  • Key 属于账户,账户下所有 API Key 共享。
  • 不带 Key 时,每次提交都会新建任务并扣 1 积分,盲目重试可能重复扣费。
  • 已经拿到任务 ID 时,请查询该任务,不要重新提交。