限流与错误

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

处理 429

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

{
  "error": {
    "code": "LIMIT_RATE_EXCEEDED",
    "message": "请求触发了 RouteMux 的频率、并发或策略限制。请遵守 Retry-After，并使用带抖动的指数退避重试。",
    "reference": "RMX-LIMIT-4001",
    "documentation_url": "https://routemux.com/zh/docs/errors#rmx-limit-4001",
    "request_id": "req_01K0EXAMPLELIMIT",
    "retry": { "retryable": true, "strategy": "BACKOFF" },
    "billing": { "status": "NOT_BILLED" }
  }
}

退避后重试

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

各协议的错误格式

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

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

网关错误参考

错误码	HTTP	含义
`AUTH_API_KEY_REQUIRED`	401	没有发送 API 密钥。
`AUTH_INVALID_API_KEY`	401	密钥不存在或无法验证。
`AUTH_AMBIGUOUS_API_KEY`	400	多个密钥头发送了不同凭据。
`AUTH_API_KEY_INACTIVE`	403	密钥存在但已停用。
`AUTH_API_KEY_EXPIRED`	403	密钥已过期。
`LIMIT_API_KEY_QUOTA_EXHAUSTED`	429	密钥达到配置的 30 天额度。
`LIMIT_API_KEY_DAILY_QUOTA_EXHAUSTED`	429	密钥达到配置的每日额度,在该密钥所配时区的 00:00 重置。
`AUTH_ACCOUNT_SUSPENDED`	403	所属账号不能发起请求。
`BILLING_INSUFFICIENT_CREDITS`	422	钱包余额不足。
`LIMIT_RATE_EXCEEDED`	429	命中 RPM、并发或策略限制。请遵守 `Retry-After`。
`MODEL_NOT_FOUND`	404	目录中无此模型。
`MODEL_PROTOCOL_UNSUPPORTED`	400	模型未开放该协议。
`MODEL_NOT_PROVISIONED`	503	模型尚未开通。原样重试无用。
`MODEL_BUSY`	503	模型当前负载已满。可重试；请遵守 `Retry-After`。
`MODEL_UNAVAILABLE`	503	所选模型无法完成本次请求。

幂等

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

curl https://api.routemux.com/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEMUX_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