速查表
401 Unauthorized — Invalid token
原因。 服务器没有接受你的密钥，可能的原因：- 用错了密钥：必须是 RuAPI 令牌（
sk-...），而不是 OpenAI 官方密钥（sk-...）或 Anthropic 密钥（sk-ant-...）。OpenAI 和 RuAPI 的密钥长得很像，但只有 RuAPI 控制台里的那个才能用。 - 复制粘贴时混入了多余的空格或换行——这是最常见的坑。
- 密钥被禁用、删除或已过期。
- 密钥用完了它自己的额度上限（如果创建时设过上限）。这时账户总余额可能还有钱，只是这一把密钥到顶了。
- 打开 控制台 → 令牌管理，确认密钥处于启用状态、没有过期、额度没用完，必要时重新复制。
- 粘贴时确保首尾没有空格、没有换行。
- 确认请求头是
Authorization: Bearer sk-...（OpenAI 协议）或x-api-key: sk-...（Anthropic 协议）。从头核对一遍密钥与base_url的填法，见快速开始。
403 — 余额不足
原因。 账户余额用完了（或不够这次请求）。充值之前，请求都无法执行。 解决。- 用 USDT / USDC 或银行卡充值——最低 5 美元，加密货币通常 1–5 分钟到账，刷卡几秒到账。
- 注意：Agent 类工具（Claude Code、Cline、自主 Agent）和长上下文消耗 token 非常快，一分钟几十次请求是常态。
- 想避免一个项目把余额全花光，可在 控制台 → 令牌管理 给单个令牌设置消费上限——达到上限后该密钥停用，其他密钥照常工作。
404 — 请求地址不对
原因。 请求发到了不存在的路径，几乎都是base_url 写错了，正确写法取决于协议：
解决。 用上表检查
base_url。完整的地址说明见 API 参考。
503 — 模型不可用（model_not_found）
原因。 几乎都是目录里没有这个 ID 的模型。model 字段必须与价格页上的模型 ID 完全一致——连字符、前缀、大小写都要对（GLM-5.2 和 glm-5.3 写法不同，kimi/kimi-k3 要带前缀）。别名或“差不多”的名字都不行。
返回里会有 "code": "model_not_found"，error.message 写的是“模型 gpt-5 当前不可用。请在「价格」页核对模型名称，或稍后重试。”
解决。 从价格页复制模型 ID，原样填进 model。如果 ID 确定没错，说明模型暂时不可用，过一分钟再试。
429 — Too Many Requests / rate limit
原因。 短时间内请求过多——要么是你的代码在批量猛发，要么是模型厂商临时限流。RuAPI 本身对每个账户的请求频率也有上限，正常使用、包括 Agent 在内，都远远碰不到。 解决。- 放慢节奏，用指数退避重试：1 秒、2 秒、4 秒、8 秒……
- 把负载分散到不同时间，别一次性发几百个请求。
- 批量任务可在请求之间加一点间隔，或限制并发数。
5xx — 500 / 502 / 503 / 上游错误
原因。 模型厂商或网关的临时故障，与你的密钥或代码无关。（例外：503 且 code 是 model_not_found，那几乎都是模型名写错了，见上文。）
解决。
- 过几秒重试——通常第二、三次就能成功。
- 把调用包进“重试 + 退避”逻辑，避免这种波动让脚本崩溃。
- 如果错误长时间持续、且在不同模型上都出现，请把报错里的
request id一并发到 support@ruapi.ai。
流式中断与超时
长回复（大上下文、推理模型、代码生成）可能要几十秒。如果连接在流式传输中途断开、或客户端超时——请调大 SDK 里的timeout（重请求设为 60–120 秒甚至更高），确认你和 RuAPI 之间没有会掐断长 SSE 连接的代理，并且不要为长回复关闭流式——正是流式传输在防止请求超时。
还是不行？
发邮件到 support@ruapi.ai：附上错误码、error.message 的完整内容（包括 request id）、模型名和请求时间，我们会很快帮你解决。