速查表
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 非常快,一分钟几十次请求是常态。
- 想避免一个项目把余额全花光,可在 控制台 → 令牌管理 给单个令牌设置消费上限——达到上限后该密钥停用,其他密钥照常工作。
403 — 密钥没开放这个模型或额度上限不够
这两种报错说的是密钥自己的设置,和账户余额无关。404 — 请求地址不对
原因。 请求发到了不存在的路径,几乎都是base_url 写错了,正确写法取决于协议:
解决。 用上表检查
base_url。完整的地址说明见 API 参考。
400 — 请求本身有问题
原因。 请求里的内容模型接受不了,具体原因写在error.message 里。常见的有:
- 工具参数的格式(JSON Schema)模型不认。 报错里是模型供应商的原话,例如
Invalid JSON payload received、Unknown name …。发给 Gemini 模型的格式,我们会先自动去掉 Gemini 不认的写法($schema、additionalProperties等);还剩下的问题会原样告诉你。 - 图片或文件打不开: 链接不能从公网访问、文件损坏,或 base64 数据不完整(例如
Invalid image url)。 /v1/responses带了接着上一次回复继续的参数: 见下文。
error.message 修改请求。以前这类问题有时会显示成 500,现在统一返回 400 并写明原因。
视频生成:按任务号引用视频的错误码。 用 reference_video_task_id 接着用生成过的视频时,可能返回 ref_task_not_found、ref_task_not_ready、ref_task_failed、ref_task_expired、ref_task_unavailable 或 unsupported_by_channel,这次不扣费。每个错误码的原因和办法见视频生成教程里「按任务号引用已生成的视频」一节。
视频生成:Seedance 内容审核报错。 input_contains_real_person、input_copyright_restricted、InputImageSensitiveContentDetected.PrivacyInformation、...PolicyViolation、OutputVideoSensitiveContentDetected 这类错误码(前两个在提交时的响应里,火山方舟官方错误码在任务的 error 字段里)来自 Seedance 模型自己的审核,被拒的任务不扣钱。每个错误码的说明:图片或视频里有真人、版权和违规内容。
/v1/responses:不支持接着上一次的回复继续
RuAPI 不在服务器上保存对话,所以 Responses 接口不支持 previous_response_id、conversation 和后台模式 background。带了这些参数会直接返回 400(不扣费),报错里写明是哪个参数。请在每次请求的 input 里带上完整的对话历史——Codex CLI 默认就是这样发的,不受影响。
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 秒……
- 把负载分散到不同时间,别一次性发几百个请求。
- 批量任务可在请求之间加一点间隔,或限制并发数。
video_concurrency_limit。 每个账号同时最多 3 条没结束的视频任务。再提交的任务会马上收到 429,错误码 video_concurrency_limit,并带 Retry-After: 30 响应头,这次不扣费。等其中一条结束后再提交即可。需要同时跑更多任务,请联系客服:发邮件到 support@ruapi.ai,或在 Telegram 找 @RuAPI_Support。详见视频生成教程。
5xx — 500 / 502 / 503 / 上游错误
原因。 模型厂商或网关的临时故障,与你的密钥或代码无关。(例外:503 且 code 是 model_not_found,那几乎都是模型名写错了,见上文。)
解决。
- 过几秒重试——通常第二、三次就能成功。
- 把调用包进「重试 + 退避」逻辑,避免这种波动让脚本崩溃。
- 如果错误长时间持续、且在不同模型上都出现,请把报错里的
request id一并发到 support@ruapi.ai。
流式中断与超时
长回复(大上下文、推理模型、代码生成)可能要几十秒。如果连接在流式传输中途断开、或客户端超时——请调大 SDK 里的timeout(重请求设为 60–120 秒甚至更高),确认你和 RuAPI 之间没有会掐断长 SSE 连接的代理,并且不要为长回复关闭流式——正是流式传输在防止请求超时。
Claude Code 的报错
Claude Code 自己提示的「Unable to connect to Anthropic services」「Invalid API key · Please run /login」等报错,见在俄罗斯用 Claude Code。报错不是 RuAPI 返回的,而是 OpenAI、Google、Anthropic 或 DeepSeek 直接返回的
如果你直接调用官方 API,因为所在地区被拒,每种报错的说明在这里:unsupported_country_region_territory(403,OpenAI)— OpenAI:unsupported_country_region_territoryUser location is not supported for the API use(400,Gemini)— Gemini:User location is not supportedRequest not allowed(403)和not allowed from unsupported countries(400,Claude)— Claude:Request not allowed
Insufficient Balance(402)— DeepSeek:402 Insufficient Balance。
还是不行?
在 Telegram 联系客服,或发邮件到 support@ruapi.ai:附上错误码、error.message 的完整内容(包括 request id)、模型名和请求时间,我们会很快帮你解决。