错误码
最近更新: 2026-10-22
未被受理的请求会返回非 2xx 状态码和 JSON 错误信息。被拒绝的请求不会创建任务,也不会扣费。
{
"error": {
"code": "insufficient_credits",
"message": "There are not enough available credits."
},
"request_id": "5b0d2f4e-1c3a-4e6b-8d7f-9a0b1c2d3e4f"
}
| 字段 | 类型 | 说明 |
|---|---|---|
error.code | string | 稳定的机器可读错误码,请据此判断处理逻辑。 |
error.message | string | 给人看的说明,内容可能调整。 |
request_id | string | 同时出现在 X-Request-Id 响应头中。联系支持时请附上。 |
错误码列表
| HTTP | error.code | 含义与处理 |
|---|---|---|
| 400 | invalid_request | 请求体不是合法 JSON,含有未定义、为 null 或重复的字段,Content-Type 不是 application/json,或 Idempotency-Key 格式不对。请修正请求。 |
| 401 | invalid_api_key | API Key 缺失、格式错误或已撤销。 |
| 402 | insufficient_credits | 没有可用积分,请购买积分或套餐。 |
| 404 | prediction_not_found | 该账户下没有这个任务。 |
| 404 | not_found | 接口地址不存在。 |
| 409 | idempotency_conflict | 这个 Idempotency-Key 已用于不同的输入。新任务请使用新的 Key。 |
| 413 | request_too_large | 请求体超过 64 KiB。 |
| 422 | invalid_image_url | 图片 URL 不是可接受的公网 HTTPS 地址。 |
| 429 | inflight_limit_exceeded | 该账户已有 50 个任务在等待或处理中,待部分任务结束后再提交。 |
| 429 | rate_limited | 查询过于频繁,按 Retry-After 秒数等待后重试。 |
| 503 | temporarily_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 时,请查询该任务,不要重新提交。