请求返回了错误而不是模型回复？在下面找到你的错误码——大多数都是两步就能解决。错误原文和请求 ID 始终可以在 控制台 → 日志 中查看。
速查表
| 错误码 | 含义 | 快速修复 |
|---|
| 401 | 密钥被拒（Invalid API key） | 填入 RuAPI 令牌 sk-...，去掉多余空格 |
| 402 | 余额用尽（Insufficient balance） | 用 USDT 充值 |
| 404 | 找不到模型（model not found） | 检查模型名和 base_url（Anthropic 协议不带 /v1） |
| 429 | 请求过多（rate limit） | 放慢节奏，用指数退避重试 |
| 5xx | 上游或网关临时故障 | 重试；若持续，联系我们 |
401 Unauthorized — Invalid API key
原因。 服务器没有接受你的密钥，通常是以下三种之一：
- 用错了密钥：必须是 RuAPI 令牌（
sk-...），而不是 OpenAI 官方密钥（sk-...）或 Anthropic 密钥（sk-ant-...）。OpenAI 和 RuAPI 的密钥长得很像，但只有 RuAPI 控制台里的那个才能用。
- 复制粘贴时混入了多余的空格或换行——这是最常见的坑。
- 密钥被禁用或删除了。
解决。
- 打开 控制台 → 令牌，确认密钥处于启用状态，必要时重新复制。
- 粘贴时确保首尾没有空格、没有换行。
- 确认请求头是
Authorization: Bearer sk-...（OpenAI 协议）或 x-api-key: sk-...（Anthropic 协议）。从头核对一遍密钥与 base_url 的填法,见快速开始。
402 — 余额不足 Insufficient balance
原因。 账户余额用完了。余额回到正数之前，请求都无法执行。
解决。
- 用 USDT 充值——最低 10 USDT，通常 1–5 分钟到账。
- 注意：Agent 类工具（Claude Code、Cline、自主 Agent）和长上下文消耗 token 非常快，一分钟几十次请求是常态。
- 想避免一个项目把余额全花光，可在 控制台 → 令牌 给单个令牌设置消费上限——达到上限后该密钥停用，其他密钥照常工作。
404 — model not found
两种完全不同的原因会产生同一个 404，两者都要检查。
原因 1 —— 模型名拼写错误。 model 字段必须与主站价格页上的模型 ID 完全一致（连字符和大小写都要对）。别名或“差不多”的名字都不行。
原因 2 —— base_url 写错了。 这是 404 最常见的隐藏原因，而且取决于协议：
| 协议 | 正确的 base_url |
|---|
| OpenAI 兼容 | https://www.ruapi.ai/v1 ← 必须带 /v1 |
| Anthropic | https://www.ruapi.ai ← 不带 /v1 |
Anthropic 协议不要在地址末尾加 /v1。SDK 会自己补上 /v1/messages，多写一个 /v1 就变成 /v1/v1/messages → 404。反过来，OpenAI 协议则必须带 /v1。
base_url。完整的地址说明见 API 参考。
429 — Too Many Requests / rate limit
原因。 短时间内请求过多——要么是你的代码在批量猛发，要么是上游供应商临时限流。
解决。
- 放慢节奏，用指数退避重试：1 秒、2 秒、4 秒、8 秒……
- 把负载分散到不同时间，别一次性发几百个请求。
- 批量任务可在请求之间加一点间隔，或限制并发数。
5xx — 500 / 502 / 503 / 上游错误
原因。 上游供应商或网关的临时故障，与你的密钥或代码无关。
解决。
- 过几秒重试——通常第二、三次就能成功。
- 把调用包进“重试 + 退避”逻辑，避免这种波动让脚本崩溃。
- 如果错误长时间持续、且在不同模型上都出现，请把 控制台 → 日志 里的请求 ID 一并发到 [email protected]。
流式中断与超时
长回复（大上下文、推理模型、代码生成）可能要几十秒。如果连接在流式传输中途断开、或客户端超时——请调大 SDK 里的 timeout（重请求设为 60–120 秒甚至更高），确认你和 RuAPI 之间没有会掐断长 SSE 连接的代理，并且不要为长回复关闭流式——正是流式传输在防止请求超时。
还是不行？
打开 控制台 → 日志 找到你的请求——里面有确切的错误码、模型和响应内容。带上这些信息发邮件到 [email protected]，我们会很快帮你解决。 
