错误码

统一失败响应结构、HTTP 状态与错误码对照表。

所有接口的失败响应结构一致：

{
  "ok": false,
  "message": "BUSINESS_RATE_LIMIT_EXCEEDED",
  "error": {
    "code": "BUSINESS_RATE_LIMIT_EXCEEDED",
    "details": null
  }
}
  • ok 恒为 false；判断成败以它为准，不要靠 HTTP 状态或 message 文案。
  • 错误类型只看 error.code：message 是给人看的，措辞可能变。
  • 参数校验失败统一是 400，error.code 以 VALIDATION_ 开头（例如 VALIDATION_VISUAL_SEARCH_IMAGE_TOO_SMALL）。

对照表

HTTP错误码说明
401UNAUTHORIZED_AUTH_REQUIRED缺少 API Key、Key 无效或被封禁（HTTP 401），错误码 UNAUTHORIZED_AUTH_REQUIRED。
403BUSINESS_INSUFFICIENT_QUOTA积分不足（HTTP 403），错误码 BUSINESS_INSUFFICIENT_QUOTA。 提交类接口在扣减积分前校验余额。
429BUSINESS_RATE_LIMIT_EXCEEDED请求频率或并发数超限（HTTP 429），错误码 BUSINESS_RATE_LIMIT_EXCEEDED。 限流校验不可用时返回 503（RATE_LIMITER_UNAVAILABLE）。 限流是动态的：额度由「你的 API 档位 × 接口所属的桶」决定， 所以同一个接口对不同调用者可能是不同的数值，这里不给出固定数字。 两处可以看到实际生效值： 1. 每次响应的 X-RateLimit-* 响应头（当次生效的次数、窗口、命中哪一档额度）； 2. GET /v2/quota/mine（带 API Key，返回你每个额度的生效值）； 另有 GET /v2/quota/config（公开）给出未分档的基线额度。 计数口径：按账号计 —— 同一账号下的所有 API Key 共享同一份额度， 多开一个 Key 不会获得额外配额。接口桶是分开计数的（例如「提交检测」与 「轮询结果」是两个桶），所以轮询不会吃掉提交的额度。
500INTERNAL_ERROR_UNKNOWN服务器内部错误（HTTP 500），错误码 INTERNAL_ERROR_UNKNOWN
503RATE_LIMITER_UNAVAILABLE请求频率或并发数超限（HTTP 429），错误码 BUSINESS_RATE_LIMIT_EXCEEDED。 限流校验不可用时返回 503（RATE_LIMITER_UNAVAILABLE）。 限流是动态的：额度由「你的 API 档位 × 接口所属的桶」决定， 所以同一个接口对不同调用者可能是不同的数值，这里不给出固定数字。 两处可以看到实际生效值： 1. 每次响应的 X-RateLimit-* 响应头（当次生效的次数、窗口、命中哪一档额度）； 2. GET /v2/quota/mine（带 API Key，返回你每个额度的生效值）； 另有 GET /v2/quota/config（公开）给出未分档的基线额度。 计数口径：按账号计 —— 同一账号下的所有 API Key 共享同一份额度， 多开一个 Key 不会获得额外配额。接口桶是分开计数的（例如「提交检测」与 「轮询结果」是两个桶），所以轮询不会吃掉提交的额度。

限流响应头

429 与正常响应都会带这几个头，可以据此提前降速：

头含义
X-RateLimit-Limit该分组每分钟上限
X-RateLimit-Remaining本分钟剩余次数
X-RateLimit-Reset额度重置的 Unix 时间戳（秒）
X-RateLimit-Route命中的限流分组
X-RateLimit-Window统计窗口长度（秒）
X-RateLimit-Concurrency本桶允许的并发请求数（0 = 不限）