<!-- Generated by web/scripts/generate-public-discovery.mjs from web/src/data/onboarding-md. Do not edit by hand. -->

# 常见错误 · 看 HTTP code + 错误 message 对号入座

> 客服 / agent 解决问题第一步：**告诉我你的完整 error JSON + HTTP code + 用什么工具/模型/group**。光说 "我报错了" 没人能猜。

---

## 报错时先抓的信息

```
{
  "工具": "Claude Code / Codex / Cherry Studio / curl",
  "base_url": "https://beefapi.com 或 https://beefapi.com/v1",
  "model": "比如 claude-sonnet-4-6 / gpt-5.5",
  "group": "claude-vip / gpt-plus / ...",
  "HTTP code": "401 / 429 / 524 / 500 / ...",
  "完整 error body JSON": "把上游返的 error 整段贴过来",
  "request_id": "如果有，response header X-Request-Id 也贴上"
}
```

把这 7 项发给客服，可以更快定位问题。

---

## 401 Unauthorized

### 现象

```
{"error": {"code": "invalid_api_key", "message": "Incorrect API key provided"}}
```

或 Claude Code 提示：

```
exceeded retry limit, last status: 401 Unauthorized
```

### 排查清单

1. **key 拼写**：从 BeefAPI 控制台 → 令牌 → 点 "复制"，**不要手打**。`sk-` 开头，长度 ~50 字符
2. **key 过期**：BeefAPI 控制台 → 令牌 → 看 "过期时间"
3. **key 被删了**：可能你不小心删掉了，控制台对照令牌列表
4. **shell 残留旧 env**：
   - 查：`env | grep -i ANTHROPIC` 或 `env | grep -i OPENAI`
   - 看到旧 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` 残留 → 改/删，重启终端
   - **Codex 用户特别坑**：装过别的中转可能在 `~/.zshrc` 留 `OPENAI_BASE_URL` 指别处
5. **header 错填**：
   - Claude Code 用 `ANTHROPIC_AUTH_TOKEN`，**不是** `ANTHROPIC_API_KEY`
   - OpenAI 兼容用 `Authorization: Bearer sk-xxx`，**不是** `OpenAI-Api-Key`
6. **base URL 不对**：
   - Claude Code 用 `https://beefapi.com`（**不加** `/v1`）
   - OpenAI 兼容必须 `https://beefapi.com/v1`（**必须加** `/v1`）

### 终极排查（Windows）

```cmd
cmd /c "echo OPENAI ENV CHECK & ^
if defined OPENAI_API_KEY (echo OPENAI_API_KEY = SET) else (echo OPENAI_API_KEY = MISSING) & ^
if defined OPENAI_BASE_URL (echo OPENAI_BASE_URL = SET) else (echo OPENAI_BASE_URL = MISSING) & ^
if defined ANTHROPIC_AUTH_TOKEN (echo ANTHROPIC_AUTH_TOKEN = SET) else (echo ANTHROPIC_AUTH_TOKEN = MISSING)"
```

### 终极排查（macOS / Linux）

```bash
env | grep -iE "openai|anthropic|claude"
```

看到不该有的旧 var → 找对应 `~/.zshrc` / `~/.bashrc` 删掉相关 `export` 行 → 重启终端。

---

## 404 Not Found / `model_not_found`

### 现象

```
{"error": {"code": "model_not_found", "message": "The model 'gpt-5.5' does not exist"}}
```

### 99% 是 group / model 不匹配

你的令牌 group **不包含**你请求的 model。例：

- 令牌 group = `claude-vip` → 只能用 claude 系，请求 `gpt-5.5` → 404
- 令牌 group = `gpt-plus` → 只能用 gpt 系，请求 `claude-sonnet-4-6` → 404

**修复**：

1. **改令牌 group** —— 控制台 → 令牌 → 新建一个对的 group 的令牌（旧的可以删）
2. **或改工具配置 model 名** —— 改成当前 group 包含的 model

完整 group → model 映射见 [分组与模型](/docs/onboarding/groups-models)。

### 1% 是 model 拼写错

`gpt-5.5` 写成 `gpt-5-5` 或 `gpt5.5` → 也 404。

去 https://beefapi.com **模型广场** 复制官方名。

---

## 429 Too Many Requests / 速率限制

### 现象

```
{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached"}}
```

或：

```
codex account rate-limited (429)
```

### 原因

- 单 key 同时并发请求太多
- 上游账号被限速（你这条线路繁忙）

### 修复

1. **降低并发**：如果你脚本里多线程同时打，先 1 线程跑测试
2. **等 30-60 秒重试**：单纯偶发限速，一会儿就好
3. **持续 429**：可能上游线路繁忙，联系在线客服处理
4. **gpt-vip 老分组**：直接停了用，建新令牌选 `gpt-plus` / `gpt-pro`

---

## 524 / Gateway Timeout

### 现象

Cloudflare 524（100s 超时）或 504 Gateway Timeout。

### 原因

- 上游模型推理超时（复杂任务 / opus 长推理 / 大 PDF / Codex 深推理 effort=high+long task）
- 上游 down

### 修复

1. **减小请求体**：长 PDF / 大上下文先 chunk
2. **切轻量模型**：opus → sonnet → haiku，gpt-5.5 → gpt-5.4-mini
3. **降 reasoning_effort**：Codex 把 `model_reasoning_effort = "high"` 改 `"medium"` / `"low"`
4. **重试 3 次**：偶发超时，重试通常 OK
5. **持续 524**：联系在线客服，可能是上游全局问题

---

## "Unable to connect to Anthropic services"

### 现象

```
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR BAD REQUEST
```

### 原因

Claude Code 配置没生效，还在连官方 `api.anthropic.com`（被墙）。

### 修复

确认 `~/.claude/settings.json` 内 `ANTHROPIC_BASE_URL` 是 `https://beefapi.com`（不是默认 `api.anthropic.com`）。

如果用 env 变量：

```bash
echo $ANTHROPIC_BASE_URL  # macOS / Linux
echo %ANTHROPIC_BASE_URL%  # Windows
```

应该输出 `https://beefapi.com`。没输出 → `.zshrc` / `.bashrc` 没生效，重启终端。

或者首次安装绕过 onboarding 检查：

**macOS / Linux**：

```bash
jq '. + {"hasCompletedOnboarding": true}' ~/.claude.json > /tmp/cc.json && mv /tmp/cc.json ~/.claude.json
```

**Windows (PowerShell)**：

```powershell
$f = "$env:USERPROFILE\.claude.json"
$j = Get-Content $f | ConvertFrom-Json
$j | Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue $true -Force
$j | ConvertTo-Json -Depth 10 | Set-Content $f
```

重启 `claude` CLI。

---

## quota_not_enough / 余额不足

### 现象

```
{"error": "quota_not_enough", "message": "用户额度不足"}
```

### 原因

钱包没钱，或令牌设了额度上限且达到。

### 修复

1. **钱包没钱** → 控制台 → 充值
2. **令牌达上限** → 控制台 → 令牌 → 编辑这个 key → 提高 / 取消 "额度"
3. **预扣费失败**：可能上次请求扣费没补结算 → 等 1 分钟自动恢复，仍不行联系在线客服

---

## Codex 用着用着觉得"降智"

很多人用一段时间 Codex 后觉得"模型变笨"。其实**不是模型降级**，而是用法问题。

### 关键：拆任务 + 别压缩

1. **不要笼统任务**：❌ "帮我写一个管理系统" ✅ "实现 User 表的 CRUD endpoint"
2. **任务开始前评估**：你能预估这次会改哪几个文件 / 产生哪些变动吗？答不出来 → 拆得不够细
3. **60% 上下文还没完成 = 拆得太粗**：Codex 一次任务最好用 60% 以内上下文。优秀用户几乎不用 `/compact`
4. **指哪打哪原则**：Codex 模型严谨有序但需要明确指令，不会"猜"你想要什么

### 关闭 1M 上下文（更省更稳）

`config.toml` 加：

```toml
model_context_window = 200000  # 200K, 不要默认 1M
```

### 提示词指南（写进 `AGENTS.md`）

```markdown
# Codex 全局工作指南

## 拆任务

- 一次只做一个小模块
- 任务开始前在脑子里 / 草稿纸上预估改动文件
- 60% 上下文未解决 = 立即停, 拆细重做

## 回答风格

- 中文
- 表格、列表用 Markdown 美化
- 代码改动前用 `/diff` 看 full diff
```

---

## 网络代理（梯子）相关

如果你电脑开了梯子，部分请求可能被代理劫持失败。

**症状**：偶发 connection error / SSL cert error / 长时间 hang

**排查**：

1. 临时关梯子重试
2. 把 `beefapi.com` 加入代理白名单（不走代理直连）
3. Clash 用户：把 MTU 改 1500（默认有时太小）

---

## 仍然解决不了？

联系在线客服时，把上面 "报错时先抓的信息" 7 项一起发过去。

---

## 下一步

- [分组与模型](/docs/onboarding/groups-models) - 选对 group 防 404
- [常见问题](/docs/onboarding/faq) - 账号 / 充值 / 令牌 / 工具配置