> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 错误码与解决办法

> 常见大模型 API 错误详解：401、402、404、429、5xx，含原因与一分钟修复方法

请求返回了错误而不是模型回复？在下面找到你的错误码——大多数都是两步就能解决。错误原文和请求 ID 始终可以在 **控制台 → 日志** 中查看。

## 速查表

| 错误码     | 含义                           | 快速修复                                        |
| ------- | ---------------------------- | ------------------------------------------- |
| **401** | 密钥被拒（`Invalid API key`）      | 填入 RuAPI 令牌 `sk-...`，去掉多余空格                 |
| **402** | 余额用尽（`Insufficient balance`） | [充值](/zh/topup) —— USDT / USDC 或银行卡         |
| **404** | 找不到模型（`model not found`）     | 检查模型名和 `base_url`（Anthropic 协议**不带** `/v1`） |
| **429** | 请求过多（`rate limit`）           | 放慢节奏，用指数退避重试                                |
| **5xx** | 上游或网关临时故障                    | 重试；若持续，[联系我们](mailto:support@ruapi.ai)      |

## 401 Unauthorized — Invalid API key

**原因。** 服务器没有接受你的密钥，通常是以下三种之一：

* 用错了密钥：必须是 **RuAPI 令牌**（`sk-...`），而不是 OpenAI 官方密钥（`sk-...`）或 Anthropic 密钥（`sk-ant-...`）。OpenAI 和 RuAPI 的密钥长得很像，但只有 RuAPI 控制台里的那个才能用。
* 复制粘贴时混入了**多余的空格或换行**——这是最常见的坑。
* 密钥被**禁用**或删除了。

**解决。**

1. 打开 **控制台 → 令牌**，确认密钥处于启用状态，必要时重新复制。
2. 粘贴时确保首尾没有空格、没有换行。
3. 确认请求头是 `Authorization: Bearer sk-...`（OpenAI 协议）或 `x-api-key: sk-...`（Anthropic 协议）。从头核对一遍密钥与 `base_url` 的填法,见[快速开始](/zh/quickstart)。

## 402 — 余额不足 Insufficient balance

**原因。** 账户余额用完了。余额回到正数之前，请求都无法执行。

**解决。**

* 用 USDT / USDC [充值](/zh/topup)——最低 5，通常 1–5 分钟到账。
* 注意：**Agent 类工具**（Claude Code、Cline、自主 Agent）和长上下文消耗 token 非常快，一分钟几十次请求是常态。
* 想避免一个项目把余额全花光，可在 **控制台 → 令牌** 给单个令牌设置**消费上限**——达到上限后该密钥停用，其他密钥照常工作。

## 404 — model not found

两种完全不同的原因会产生同一个 404，两者都要检查。

**原因 1 —— 模型名拼写错误。** `model` 字段必须与主站[价格页](https://www.ruapi.ai/pricing)上的模型 ID **完全一致**（连字符和大小写都要对）。别名或“差不多”的名字都不行。

**原因 2 —— `base_url` 写错了。** 这是 404 最常见的隐藏原因，而且取决于协议：

| 协议            | 正确的 `base_url`                             |
| ------------- | ------------------------------------------ |
| **OpenAI 兼容** | `https://www.ruapi.ai/v1`  ← **必须带 `/v1`** |
| **Anthropic** | `https://www.ruapi.ai`  ← **不带 `/v1`**     |

<Warning>
  Anthropic 协议**不要**在地址末尾加 `/v1`。SDK 会自己补上 `/v1/messages`，多写一个 `/v1` 就变成 `/v1/v1/messages` → **404**。反过来，OpenAI 协议则**必须**带 `/v1`。
</Warning>

**解决。** 先对照价格页核对模型 ID，再用上表检查 `base_url`。完整的地址说明见 [API 参考](/zh/api-reference)。

## 429 — Too Many Requests / rate limit

**原因。** 短时间内请求过多——要么是你的代码在批量猛发，要么是上游供应商临时限流。

**解决。**

* 放慢节奏，用**指数退避重试**：1 秒、2 秒、4 秒、8 秒……
* 把负载分散到不同时间，别一次性发几百个请求。
* 批量任务可在请求之间加一点间隔，或限制并发数。

## 5xx — 500 / 502 / 503 / 上游错误

**原因。** 上游供应商或网关的临时故障，与你的密钥或代码无关。

**解决。**

* 过几秒**重试**——通常第二、三次就能成功。
* 把调用包进“重试 + 退避”逻辑，避免这种波动让脚本崩溃。
* 如果错误长时间持续、且在不同模型上都出现，请把 **控制台 → 日志** 里的请求 ID 一并发到 [support@ruapi.ai](mailto:support@ruapi.ai)。

## 流式中断与超时

长回复（大上下文、推理模型、代码生成）可能要几十秒。如果连接在流式传输中途断开、或客户端超时——请调大 SDK 里的 `timeout`（重请求设为 60–120 秒甚至更高），确认你和 RuAPI 之间没有会掐断长 SSE 连接的代理，并且不要为长回复关闭流式——正是流式传输在防止请求超时。

## 还是不行？

打开 **控制台 → 日志** 找到你的请求——里面有确切的错误码、模型和响应内容。带上这些信息发邮件到 [support@ruapi.ai](mailto:support@ruapi.ai)，我们会很快帮你解决。