---
title: 错误码与排错
description: 调用 1折AI 时遇到 401、404、429、529、5xx、超时和 Claude Code 报错时，原因和处理办法。
---

先按顺序过一遍下面的清单，大多数问题在前三步就能找到。

## 排查顺序

1. **地址**：Anthropic 系工具填 `https://1zheai.com`，OpenAI 系填 `https://1zheai.com/v1`。见 [Base URL 与鉴权](/docs/base-url/)。
2. **API 密钥（API key）**：是否完整（没有多余空格、换行）、是否已被删除、是否填进了正确的字段。
3. **余额**：控制台里余额是否充足。
4. **模型 ID**：是否和[支持的模型](/docs/models/)里的完全一致。
5. **网络**：关掉代理直连再试一次。
6. **还不行**：拿一条最小的 curl 复现（见下），把回包和时间发给我们。

```bash title="最小复现"
curl -i https://1zheai.com/v1/messages \
  -H "x-api-key: sk-你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
```

`-i` 会把状态码和响应头一起打印出来，排查时很有用。

## 错误码速查

| 状态码 | 常见原因 | 怎么办 |
|---|---|---|
| 400 | 请求体有问题：参数名错、字段类型错、`max_tokens` 超过模型上限、带了上游不认的 beta 字段 | 看 `message` 里指出的字段；Claude Code 的情况见下文"Extra inputs are not permitted" |
| 401 | API 密钥无效、已删除、已禁用、已过期、自身额度用完，或没带、放错了请求头 | 回包都是 `Invalid token`，逐项检查；Anthropic 原生用 `x-api-key` 或 `Authorization: Bearer` |
| 403 | 账户余额不足（`billing_error` / `insufficient_quota`）；这个 API 密钥没开通该模型；请求 IP 不在这个 API 密钥的白名单里（都是 `permission_error`） | 充值，或在「API 密钥」页编辑这个 API 密钥的模型限制和 IP 白名单 |
| 404 | 路径不对，或模型不存在 / 当前不可用 | `Invalid URL` 核对地址；`not_found_error` / `model_not_found` 核对模型 ID 和可用列表 |
| 413 | 请求体太大 | 减少一次发送的内容，大文件分段 |
| 429 | 上游临时限流。目前我们不对 API 密钥设速率限制 | 稍后重试，批量任务加指数退避 |
| 503 | 模型存在但暂时没有健康的上游服务，或服务临时故障 | 稍后重试；持续失败时提供请求 ID 联系支持 |
| 500 / 502 | 网关或上游临时故障 | 稍后重试；持续出现发邮件到 support@1zheai.com |
| 504 | 请求超时 | 长输出用流式；调大客户端超时 |
| 529 | 上游 Anthropic 过载（`overloaded_error`） | 等几秒重试，或临时换一个模型 |

Anthropic 官方错误类型（`invalid_request_error`、`authentication_error`、`rate_limit_error`、`overloaded_error` 等）的完整含义见[官方 Errors 文档](https://platform.claude.com/docs/en/api/errors)。

上游返回的错误，状态码和 `message` 原样带回，`message` 末尾加上本次请求的 request id。走 `/v1/messages` 时外层是官方的 `{"type":"error","error":{...}}` 结构，`error.type` 按状态码填官方类型；走 `/v1/chat/completions` 时是 OpenAI 的 `{"error":{...}}` 结构。

## 实测回包

下面是 2026-10-15 对 `/v1/messages` 实测的真实回包。走 `/v1/chat/completions` 时内容相同，外层没有 `"type":"error"`，`error` 里多一个 `code` 字段。

<CodeGroup>
```json title="401 API 密钥无效、禁用、过期或额度用完"
{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}
```
```json title="403 账户余额不足"
{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}
```
```json title="403 API 密钥没开通该模型"
{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}
```
```json title="403 IP 不在白名单"
{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}
```
```json title="400 上游参数错误"
{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}
```
```json title="404 路径不存在"
{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}
```
</CodeGroup>

模型不存在或不可用时的 404 说明见[支持的模型](/docs/models/)。回包里的 request id 对应你的这一次请求，反馈问题时带上它。

## 按症状排查

### 401 / Invalid token

- API 密钥复制时多了空格或换行，重新复制一次。
- API 密钥已在控制台删除或禁用，或者已过期、自身额度已用完。这几种情况的回包都是同一句 `Invalid token`。
- Claude Code 里同时设置了 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN`，而其中一个是旧值：两个只留一个，推荐 `ANTHROPIC_AUTH_TOKEN`。
- `settings.json` 的 `env` 会覆盖终端里 export 的同名变量，改了终端变量不生效时，检查 `~/.claude/settings.json`。

### 404 / Invalid URL

先看错误类型：`not_found_error` 或 `model_not_found` 要检查[模型 ID 与可用列表](/docs/models/)。`Invalid URL` 则检查 `/v1`：OpenAI SDK、Cursor、Cline（OpenAI Compatible）要填到 `https://1zheai.com/v1`；Claude Code 和 Anthropic SDK 只填 `https://1zheai.com`，填了 `/v1` 会变成 `/v1/v1/messages`。

### 403 / error code: 1010

回包只有 `error code: 1010` 这一行、没有 JSON，说明请求在到达网关前被拦下了。目前已知用 Python 标准库 `urllib` 直接发请求会遇到（它默认的 User-Agent 是 `Python-urllib/3.x`）。在请求头里加一个自己的 `User-Agent`，或者改用官方 SDK、`requests`、`httpx`。

### 429 太多请求

目前不对 API 密钥设速率限制。收到 429，通常是上游负载高，稍后重试即可。批量任务建议加指数退避：失败后等一段时间再试，每次等待时间翻倍，并自己用队列控制并发。

### 529 / overloaded_error

上游 Anthropic 暂时过载，和你的 API 密钥、余额无关。等几秒重试；赶时间的话临时换到同系列的另一个模型。

### 超时、流式中途断开

- 长回答尽量用流式（`"stream": true`），不容易被中间网络设备掐断。
- Claude Code 可以用 `API_TIMEOUT_MS` 调大超时，默认 600000（10 分钟）。
- 开着代理的话，先关代理试一次，很多断流来自代理节点。

### Claude Code：直接进了登录界面

说明 Claude Code 没读到你的 API 密钥。在 Claude Code 里运行 `/status`，看 base URL 和凭据来源两行；为空就回到 [Claude Code 接入](/docs/quickstart-claude-code/)检查环境变量或 `settings.json`。

### Claude Code：Extra inputs are not permitted / context_management 报 400

Claude Code 会在请求里带一些实验性的 beta 字段，严格的上游不认就会报 400。设置下面的环境变量关掉它们（来自 Claude Code 官方 LLM gateway 文档）：

```bash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
```

### 余额充足但调用失败

- 如果只有某个模型失败，可能是该模型暂时不可用、ID 写错，或者这个 API 密钥设了模型限制（403 `This token has no access to model …`）。
- 如果全部失败且是 401，看看这个 API 密钥是不是设了额度上限并且已经用完，或者已经过期。在「API 密钥」页的「额度 ($)」和「过期」两列能看到。
- 其它情况看上面的错误码表。

## 还是没解决

发邮件到 support@1zheai.com，附上时间、模型 ID、你用的工具和版本、`curl -i` 的完整输出（删掉 API 密钥）。