先看懂报错长什么样
不管你用 Codex、Claude Code 还是 Cherry Studio，报错都来自同一处：小店服务器回了一个三位数「状态码」，再加一句英文原文。各个工具显示的样子不同，但抓住这两样就够了。
{
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
}下表按状态码速查，先对号入座，再看后面对应的小节。
| 状态码 | 原文（节选） | 多半是 |
|---|---|---|
| 401 | Invalid API key / API key is disabled | 密钥不对或被停用 |
| 403 | Insufficient account balance | 余额为 0 |
| 403 | API key 已过期 / 所属分组已停用 | 密钥本身的限制 |
| 404 | Model "..." is not available for this group | 模型名错或分组没这个模型 |
| 429 | Concurrency limit exceeded for user | 同时发的请求太多 |
| 502 / 503 | Upstream service temporarily unavailable | 上游临时故障，稍后重试 |
401、余额、403：密钥、钱和权限
401：Invalid API key
现象：Codex 显示 401 Unauthorized；Cherry Studio 弹出红色提示，原文是 Invalid API key。
原因：
- 复制时多了空格、少了字符，或只复制了一半。
- 密钥已在 API 密钥 页删除或停用，原文会变成 API key is disabled。
- 根本没填密钥，原文以 API key is required in Authorization header 开头。
- 密钥填对了，但接口地址还是官方的，等于拿小店密钥去敲别家的门。
怎么做：到 /keys 重新创建一把；密钥明文只显示一次，建议直接用「使用」弹窗整段复制，不要手敲。想确认密钥是否有效，可以在终端运行：
curl https://api.zyuou.com/v1/models \
-H "Authorization: Bearer sk-你的密钥"能列出模型就说明密钥没问题，问题在工具配置，回 快速开始 核对地址。
余额不足：Insufficient account balance
现象：状态码 403，原文 Insufficient account balance。小店用 403 而不是 402 表示欠费，普通聊天请求不会见到 402。
原因：余额已经是 0。注册不送额度，第一次用一定要先充。
怎么做：按 充值与兑换 买一张余额兑换卡，到 /redeem 粘贴卡密，额度即时到账。
403：其它「不让用」
原因对照原文：
- API key 已过期：创建密钥时设了有效期。
- API Key 所属分组已停用 / 已删除：店主调整了分组，换一把密钥。
- Access denied. Your IP is ...：密钥设了 IP 白名单，而你换了网络。
- This group is restricted to Claude Code clients (/v1/messages only)：该分组只给 Claude Code 用，换工具或换分组。
怎么做：前三种到 /keys 点开密钥详情，改掉有效期、IP 限制，或者重建。注意「分组里没有这个模型」不是 403，而是 404，见下一节。另外，原文含 content_policy_violation 或 Request blocked by upstream cyber-security policy 的，是内容被审核拦下，状态码不固定，换个说法再试。
404 和 429：模型名与限流
404：model_not_found
现象：原文两种：Model "xxx" is not available for this group，或 Model "xxx" is not supported by any configured account in this group。
原因：模型名拼错（gpt-6.1-sol 不是 gpt6.1-sol），或者这把密钥所在的分组没有该模型。比如用「国模」分组的密钥去调 gpt-6.1-sol，用「CC MAX正价分组」的密钥去调 GPT。
怎么做：对照 分组怎么选 里的表，确认模型属于哪个分组；需要的话到 /keys 新建一把对应分组的密钥。Cherry Studio、ChatBox 里手动添加模型名时，要和表里一字不差。
429：发得太多、太快
现象：Codex 只会显示 exceeded retry limit, last status: 429，看不到原文；其它工具能看到下面几句之一。
| 原文 | 意思 |
|---|---|
| Concurrency limit exceeded for user | 同时在跑的请求超过了你的并发上限，排了一会儿队也没排到 |
| Too many pending requests | 排队的位置也满了 |
| api key 5小时限额已用完（或 日限额 / 7天限额） | 你自己给这把密钥设的限额 |
| Upstream rate limit exceeded / All available accounts are currently rate-limited | 上游忙，和你无关 |
并发是按账号算的，你所有密钥共用一个上限；/keys 页的「当前并发」列能看到每把密钥正在跑几个请求，/redeem 页顶部能看到你的并发数。
怎么做：等几秒再试；不要同时开好几个 Codex 窗口跑任务；上游忙就换到 24 小时自动调度的兜底分组；需要更高并发找客服。
超时和中途断流
现象：转圈很久后报 timeout；回答写到一半停了；或者看到 502 / 503，原文 Upstream service temporarily unavailable、No available accounts。
原因：高峰期上游排队，长输出耗时久，或你本地网络抖动。按默认配置，小店等上游开始回答最多 600 秒；流式输出中 180 秒没有新内容就会断开，等待期间每 10 秒发一次心跳保活。
怎么做：先原样重试一次；还不行换一个分组；把一个大任务拆成几个小的；503 一般几分钟内自己恢复。重试前可以到 /usage 看一眼刚才那次有没有记录。
找客服前先准备什么
带齐下面六样，客服一次就能定位，不用来回问：
- 工具名和版本：如 Codex CLI、Claude Code、Cherry Studio。
- 模型名：你请求里写的那个。
- 报错原文：状态码加整句英文，完整复制，别只截一半。
- 发生时间：精确到分钟。
- 密钥名称：/keys 里给它起的名字，不要发密钥本身。
- 一张 /usage 的截图，能看到那段时间有没有记录。
还是不行？
先回到本文开头的速查表（常见报错）再对一遍状态码。还是卡住，加 QQ 群 1104498354（备注「新手」）或联系客服 QQ 3480261526，把上一节的六样材料一起发过去。