限流与错误

OneHop 在上游供应商限制之上施加自己的限流策略。该策略管控每账号每分钟请求数和并发流数, 并按请求逐次解析 —— 先看密钥的策略,再看账号的策略,最后回退平台默认。

处理 429

超过限制时,网关按入口协议的错误格式返回 RATE_LIMITED,HTTP 429。

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  }
}

退避后重试

把 429 当作瞬态。用带抖动的指数退避重试,而不是猛打端点。如果你持续撞限, 请联系客服申请更高的策略档位。

各协议的错误格式

错误按你调用的家族格式返回,所以你现有的 SDK 错误处理照常工作:

/v1/* 和 /responses —— OpenAI 错误格式。
/anthropic/* 和 /v1/messages —— Anthropic 错误格式。
/vertex-ai/* —— Gemini / Google 错误格式。

网关错误参考

错误码	HTTP	含义
`API_KEY_REQUIRED`	401	没有发 API 密钥。
`INVALID_API_KEY`	401	密钥不存在或已撤销。
`AMBIGUOUS_API_KEY`	400	同时发了多个密钥头。
`USER_BLOCKED`	403	所属账号已被禁用。
`INSUFFICIENT_CREDITS`	422	钱包余额低于地板。
`RATE_LIMITED`	429	命中 RPM、并发或策略限制。
`MODEL_NOT_FOUND`	404	目录中无此模型。
`MODEL_PROTOCOL_NOT_SUPPORTED`	400	模型未开放该协议。
`MODEL_TEMPORARILY_UNAVAILABLE`	503	已发布的模型被暂停,而非移除。
`SUB2API_POOL_UNAVAILABLE`	503	无可用上游容量。
`UPSTREAM_TIMEOUT`	504	上游超时。
`UPSTREAM_ERROR`	502	上游返回 5xx。

幂等

发 X-Idempotency-Key 头,让请求可安全重试:

curl https://api.onehop.ai/v1/chat/completions \
  -H "Authorization: Bearer $ONEHOP_API_KEY" \
  -H "X-Idempotency-Key: idem_2026_06_19_001" \
  -H "Content-Type: application/json" \
  -d '{ "model": "openai/gpt-4o-mini", "messages": [{ "role": "user", "content": "hi" }] }'

如果同一键的请求仍在途中,你会得到 IDEMPOTENCY_IN_PROGRESS(409),且不会再次调用上游。
如果它已经完成,你会得到 IDEMPOTENCY_REPLAY_UNAVAILABLE(409)—— 请求不会被重复扣费, 但原始响应体不会被重放。

幂等键按账号范围生效,防止重试与对账造成重复扣费。

限流与错误

处理 429

各协议的错误格式

网关错误参考

幂等

On this page