给 AI

错误码

所有接口同一种错误结构,告诉你有没有扣费、要不要重试。判断看 code,不看 message:message 是每个 code 固定的一句话,具体哪里不对写在 problems 和 param 里。

codeHTTP扣费重试含义怎么办
invalid_params400否修正后重试参数缺失、类型或取值不对,或者请求方法不对。problems 列出每一处问题,param 是第一个出错的参数。按 problems 改好再发。
max_price_exceeded400否修正后重试这次调用最多可能花的钱(required)超过了 X-Max-Price(或 max_price),所以没有执行。把上限调到 required 以上、少要一些条目,或者不设上限。
cursor_invalid400否不要重试这个 cursor 不是我们发出的,或者是发给别的账户的。把 page.next_cursor 原样传回,或者不带 cursor 从头开始。
cursor_mismatch400否修正后重试cursor 发到了别的接口,或者参数和它所在那一页不一样(view 和 fields 可以变)。用它所在那一页的接口和参数重新发。
unauthorized401否不要重试Key 缺失、格式不对、已撤销、已停用或已过期(知道原因时 reason 会写明)。带上 Authorization: Bearer <key>,用有效的 key;next_step 写了去哪里拿。
insufficient_balance402否修正后重试余额(available)不够这次调用的最高费用(required)。到 top_up_url 充值,到账后把同一个请求原样再发一次。
key_budget_exceeded402否修正后重试这次调用会超出这个 key 的每日、每月或总额花费上限(reason 说明是哪个)。等到下一天或下个月(UTC),在控制台调高上限,或换一个 key。
account_suspended403否不要重试这个 key 所属的账号已停用,账号下的 key 都不能用。发邮件到 hello@okdata.online。
key_scope_denied403否不要重试这个 key 的可用范围里没有这个接口。换一个包含这个接口的 key,或在控制台放宽它的范围。
unknown_endpoint404否不要重试这个路径下没有接口。路径和某个接口很接近时,moved_to(或 suggestion)会给出正确的路径。有 moved_to 就用它;否则对照目录检查 id(路径是 /v1 加上把点换成斜杠的 id)。
not_found404请求到了数据源就扣一次不要重试内容、账号或页面不存在或不公开。数据源对这次查询收了费,或者接口的 charge_when_not_found 大于 0 时,这个结果会计费:返回体里 charged 为 true,并给出 amount。这是最终结果,重试也一样。
result_not_found404否不要重试这个账号下没有这个请求号的结果(调用失败了,或从没发生)。核对请求号;只有成功的调用会保留结果。
idempotency_conflict409否修正后重试这个 Idempotency-Key 在 24 小时内已用于另一个请求。新请求用新的 key。
call_in_progress409否用同一个 Idempotency-Key 重试带这个 Idempotency-Key 的调用还在进行。稍后用同一个 key 重试,拿到它的结果,只扣一次费。
cursor_expired410否不要重试cursor 超过了这个接口的有效期(page.cursor_expires_at 写了到期时间)。不带 cursor 从头开始,跳过已经拿到的 id。
result_expired410否不要重试结果已超过 24 小时,已删除。重新调用接口(照常计费)。
rate_limited429否可以重试账号这一分钟请求太多(reason: rate),或同时进行的调用太多(reason: concurrency)。等 retry_after_seconds 秒(或等进行中的调用结束),再发同一个请求。
cost_cap_exceeded429否可以重试账号今天的花费已到每日上限。等 retry_after_seconds 秒(下一个 UTC 日),或联系我们调高。
uncharged_cost_limit429否可以重试今天没扣费的调用(查无结果)太多了。检查发送的 id;下一个 UTC 日恢复。
settlement_unknown500查询后才知道用同一个 Idempotency-Key 重试数据已返回,但没能确认是否扣费。带同一个 Idempotency-Key 重发,拿到结果且不会再扣费;或在 /v1/calls/{request_id} 查询。
internal_error500否可以重试我们这边出错了,这次没有扣费。退避后重试。
upstream_failed502请求到了数据源就扣一次可以重试这个接口的所有数据源这次都失败了。如果数据源对这次请求收了费,就按接口价格计一次费(charged 为 true,并给出 amount);否则不计费。退避后重试;持续失败就看状态页。
cursor_unavailable502否可以重试只有返回上一页的数据源能接着翻,它现在不可用。稍后用同一个 cursor 重试,或者不带 cursor 从头开始。
upstream_busy503请求到了数据源就扣一次可以重试这个接口的所有数据源都在满负荷。如果数据源对这次请求收了费,就按接口价格计一次费(charged 为 true,并给出 amount);否则不计费。退避后重试。
capability_paused503否可以重试这个接口暂时停用了,这次没有执行。看 /v1/catalog/status,恢复后再调用。
timeout504请求到了数据源就扣一次可以重试数据没有及时返回。如果请求已经到了会收费的数据源,就按接口价格计一次费(charged 为 true,并给出 amount);否则预扣退回。退避后重试。

安全重试

每次调用都带上 Idempotency-Key。24 小时内同一个 key、同一个请求会直接返回保存的结果(meta.replayed: true),不再扣费,所以结果没收到时重发,同一份结果不会扣两次。同一个 key 换了请求内容会返回 409 idempotency_conflict。

接上一次,以后直接问 AI。

新 key 自带 $0.10 试用额度。贴一句话,就能接进你的智能体。

免费开始
一句话接进你的 AI

把这句话发给你的智能体

读一下 https://okdata.online/zh/agents.md,帮我把 okdata 配好;我的 key 在环境变量 OKDATA_API_KEY 里。

Claude Code、Cursor、Codex 等能打开网址的智能体,读完会自己配好。

MCP 地址https://api.okdata.online/mcp