错误处理

所有错误返回 HTTP 状态码 + JSON,错误信息在 error 对象里;与成功响应一样,顶层带 request_id 与 timestamp:

{
  "error": { "code": "rate_limited", "message": "请求过于频繁，请稍后再试", "retryable": true },
  "request_id": "3f9a1c2b7d4e8f01",
  "timestamp": "2026-10-10T07:20:01Z"
}

合规检测系列端点的错误体多一个 "ok": false(error 对象结构相同;余额类错误在 error 内另带 need / balance):

{
  "ok": false,
  "error": { "code": "insufficient_credits", "message": "API 点余额不足", "retryable": false, "need": 50, "balance": 20 },
  "request_id": "3f9a1c2b7d4e8f01",
  "timestamp": "2026-10-10T07:20:01Z"
}

error.code:机器可读错误码(字符串,见下表)。先按 HTTP 状态码分支,再用 code 细分。
error.retryable:true = 同一请求稍后重试有望成功(限流、上游 / 数据源暂不可用、服务内部错误);false = 重试同一请求不会成功(参数、鉴权、档位、余额、路径类错误),请先修正请求或处理账户状态。
request_id / timestamp:与成功响应相同的追踪字段(见概览 · 请求追踪);向支持反馈问题时请提供 request_id。

状态码	code	retryable	含义
400	`bad_request`	false	参数或请求体不合法(如畸形 JSON、缺必填项、`batch-screen` 超过 2,000 条、`text-search` 不支持的辖区——错误信息列出当前可用清单)
400	`bad_json`	false	合规检测系列端点的请求体不是合法 JSON(与 `bad_request` 同义的历史别名)
400	`country_not_supported`	false	`/v1/image-search` 的 `country` 仅支持 US、CN
401	`invalid_key`	false	缺少或无效的 API Key
402	`quota_exceeded`	false	本月 API 点不足,需升级 / 续费 API 套餐
402	`insufficient_credits`	false	合规检测系列端点的 API 点余额不足(与 `quota_exceeded` 同义),`error` 内另带 `need` / `balance`
402	`cash_quota_exhausted`	false	赠送点不可用于第三方数据源接口，本月套餐点已用完
403	`paid_plan_required`	false	免费版调用第三方数据源接口(合规检测系列、伙伴国辖区、Listing 改写),未扣点;购买任一 API 套餐即可使用
403	`forbidden_entitlement`	false	Key 所属套餐无权使用该能力(如 EPO 检索),请升级
403	`key_owner_missing`	false	Key 有效,但绑定邮箱尚未开通 One1 账号,无法计费
404	`not_found`	false	未知的 `/v1` 接口
405	`method_not_allowed`	false	HTTP 方法错误(如对 POST 端点用了 GET);响应头 `Allow` 列出允许的方法
429	`rate_limited`	true	超出本档每账户限速(同一账户的 REST 与 MCP 共用)或同一出口 IP 合计上限;响应头 `Retry-After: 1`,请降低并发或升级套餐
500	`server_error`	true	服务内部错误,已扣点自动退回;请附 `request_id` 联系支持
502 / 503	`upstream_error`	true	合规检测系列的第三方上游不可用或调用失败,已扣点自动退回;503 时响应头 `Retry-After: 2`
503	`busy`	true	Listing 改写(`/v1/listing/fix`)并发繁忙,未扣点;响应头 `Retry-After: 5`,请按其退避后重试
503	`data_unavailable` / `country_unavailable`	true	数据源暂不可用(如伙伴国数据源超时,海关 / 政策 / EPO / Listing 改写服务不可用),未扣点或已扣点自动退回;响应头 `Retry-After: 2`
503	`epo_unavailable`	true	`/v1/epo-search` 的 EPO 检索服务(Beta)暂不可用,未扣点

可重试清单与退避

retryable: true 的 code:rate_limited、busy、upstream_error、data_unavailable、country_unavailable、server_error、epo_unavailable;其余一律 false。
响应带 Retry-After(秒)时按其等待;没有时从 1 秒起指数退避,建议最多重试 3 次。
重试请用同一入参。可重试错误下本次调用未扣点或已自动退回,重试不会造成重复扣费;重试成功后按正常计费一次。

计费保护

参数校验(含坏图、country 校验)、档位拦截(403 paid_plan_required)与限流(429 rate_limited)都在扣费之前完成,不消耗点数。调用彻底失败时已扣的点会退回。

建议按状态码分支

先按 HTTP 状态码分支处理,再用 code 细分原因。合规检测系列端点的错误体多一个 ok: false,其 bad_json / insufficient_credits 分别与 bad_request / quota_exceeded 同义,状态码与上表一致。

可重试清单与退避​

可重试清单与退避