本文汇总在云石 API 中转场景下最常见的 HTTP 状态码报错，给出对应的含义、成因与处理办法。报错时先从这里对号入座，多数问题可以自助解决。
一、适用版本与适用范围
| 项目 | 说明 |
|---|---|
| 适用服务 | 云石 API（https://yyoo.xyz）及其全部协议端点（/v1/messages、/v1/chat/completions、/v1/responses） |
| 适用客户端版本 | 不限。Claude Code、Codex、CC Switch、VS Code 插件以及各类对话客户端与 SDK 的报错都可用本文定位 |
| 文档类型 | 排查参考手册（非操作教程）。如需从零接入，请看《云石新手教程》及各软件教程 |
| 核对日期 | 2026-09-23 |
二、前置条件（排查前先确认三件事）
绝大多数报错都源于下面三要素之一写法不对。动手排查前先确认它们，能省掉大半时间：
| 要素 | 正确写法 | 写错会报 |
|---|---|---|
| 接口地址 | Claude 系：https://yyoo.xyz；OpenAI 系 / Codex：https://yyoo.xyz/v1（末尾不要再拼路径） |
404 |
| 令牌 | sk- 开头，完整、首尾无空格，且分组与所用模型匹配 |
401 / 403 |
| 模型名 | 从后台「模型广场」复制原文 | 404 / 400 |
还没接入任何客户端时，请先按《云石新手教程》完成注册与令牌创建。
三、安装配置常见错误对照
下面是配置阶段最容易踩的坑，以及它们各自的报错表现——对照「五、验证方法」可逐项确认：
| 配置写法 | 现象 | 正确做法 |
|---|---|---|
地址末尾多写 /v1/messages 或 /responses |
404 Not Found | 只写到 https://yyoo.xyz 或 https://yyoo.xyz/v1 |
Claude 工具填了带 /v1 的地址 |
404 / 路径重复 | Claude 系工具填根地址 https://yyoo.xyz |
| Codex 协议格式选了 chat | 报不支持的 API 格式 | Codex 新版只支持 responses |
| 用 gpt 分组的令牌调 Claude 模型（或反之） | 403 / 模型不存在 | 分组与模型匹配：Claude 用 Claude 分组，GPT 系用 gpt 分组 |
| 令牌复制时带了空格或少了字符 | 401 INVALID_API_KEY |
重新完整复制粘贴，不要手动输入 |
| 改了配置但没重启客户端 | 报错照旧、像没生效 | 从系统托盘完全退出后重新打开 |
环境变量类的配置（如
ANTHROPIC_BASE_URL）在修改后需要重开终端或注销一次才会生效。四、核心操作：状态码速查与处理
4.1 4xx 客户端错误
通常是请求本身的问题：优先检查参数、密钥与额度。
| 状态码 | 含义 | 中转场景常见原因 |
|---|---|---|
| 400 | Bad Request | 请求格式错误：JSON 语法错、必填字段缺失、上下文超长 |
| 401 | Unauthorized | API Key 无效或过期（也表现为 API_KEY_REQUIRED / INVALID_API_KEY） |
| 402 | Payment Required | 余额或该分组额度不足 |
| 403 | Forbidden | 无权限访问该模型或功能（额度用尽、IP 白名单等） |
| 404 | Not Found | 模型名称拼写错误，或该渠道不支持此模型；接口地址末尾多拼了路径也会 404 |
| 429 | Too Many Requests | 触发限流：并发过高或短时间请求过多 |
逐条处理建议
- 400：检查请求体是否为合法 JSON；对话类请求确认
messages等必填字段齐全；长上下文场景先开新任务压缩历史。 - 401：重新完整复制令牌（注意首尾空格）；确认令牌未被重置或删除。
- 402：到后台确认余额，以及令牌所属分组的额度是否充足。
- 403：确认令牌分组与所用模型匹配；检查是否设置过 IP 限制。
- 404：核对模型名；核对接口地址是否多写了路径。
- 429：降低并发、加请求间隔；批量任务建议串行化或加重试退避。
4.2 5xx 服务端错误
通常是服务侧问题：可稍后重试，长时间未恢复请联系客服。
| 状态码 | 含义 | 中转场景常见原因 |
|---|---|---|
| 500 | Internal Server Error | 中转服务自身 bug 或配置异常 |
| 502 | Bad Gateway | 中转向上游请求时，上游返回了无效响应 |
| 503 | Service Unavailable | 上游服务过载或维护中 |
| 504 | Gateway Timeout | 上游响应超时，多见于长上下文或上游负载高 |
逐条处理建议
- 500 / 502 / 503：先隔 1～2 分钟重试一次；若持续出现，换一个模型（可能是该上游渠道异常）再试，仍不行请联系客服并附上报错原文。
- 504：缩短单次请求的上下文长度；或换用当前负载较低的模型。
- 服务端错误若确认失败仍被扣费，请带上请求时间与模型名反馈。
五、验证方法（自查清单）
用一个最小请求就能把问题范围缩小到「令牌/服务侧」还是「客户端配置」：
curl https://yyoo.xyz/v1/models -H "Authorization: Bearer sk-你的令牌"- 这里成功、客户端失败 → 问题在客户端配置，回到第三节对照排查。
- 这里也失败 → 问题在令牌或服务侧，按第四节的对应状态码处理。
| 检查项 | 怎么查 | 正常表现 |
|---|---|---|
| 接口地址 | 对照第二节的三要素表 | Claude 系 https://yyoo.xyz；OpenAI 系 / Codex https://yyoo.xyz/v1 |
| 令牌有效 | 执行上面的最小请求 | 返回模型列表 |
| 模型可用 | 在返回的模型列表里查找你填的模型名 | 能在列表中找到 |
| 最小请求可通 | 发一条 /v1/chat/completions 单轮对话 |
返回正常回复 |
| 扣费正常 | 后台「使用记录」 | 能看到刚才这次调用的模型与 Token 消耗 |
| 客户端已重启 | 完全退出客户端进程后重开 | 配置生效 |
六、常见问题与反馈渠道
6.1 常见问题
- 同一个报错反复出现怎么办？先执行第五节的最小请求。若最小请求正常，问题一定在客户端配置，逐项对照第三节。
- 换网络环境后突然全部 403？大概率是令牌设了 IP 限制，回后台调整或清空。
- 报错消失了但代码没生成？可能是输出被截断（
max_tokens太小）或上下文超长，属 400 类问题。 - 客户端里看不到原始报错？到终端用
curl复现一次，或在客户端日志中查找状态码。
6.2 需要联系客服时请提供
- 报错状态码与完整报错原文（截图或文本）；
- 发生时间（精确到分钟，便于查日志）；
- 使用的客户端与模型名；
- 你填写的接口地址（不要附上完整令牌，最多提供前 8 位）。
也可以直接使用站内导航栏的「反馈」入口提交，内容与联系方式一并留下即可。
七、回滚 / 卸载
如果改动配置后反而全线报错，按下面的顺序回退，通常 1 分钟内即可恢复到可用状态：
- 撤回最近一次配置改动：把接口地址、令牌、模型名改回上一版（或直接删除该供应商配置）。
- 用 CC Switch 一键恢复：若用 CC Switch 管理，直接切换到之前可用的供应商并重启客户端；有备份的可用「恢复」还原本地数据库。
- 删除临时环境变量：环境变量方式接入的，删除
ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/OPENAI_API_KEY等自定义项后重开终端。 - 彻底重置单个工具：备份后删除该工具的配置目录（如
~/.codex），重新走一遍对应教程。
重置前请先备份配置目录。若令牌已确认泄露或误发他人，请到后台重置该令牌，旧令牌会立即失效。
八、更新记录
| 日期 | 版本 | 修改内容 |
|---|---|---|
| 2026-09-23 | v2.0 | 知识库检查修订：按规范补齐章节结构（适用版本、前置条件、配置错误对照、核心操作、验证方法、常见问题与反馈、回滚/卸载、更新记录）；新增 402（额度不足）与 504（上游超时）；新增配置错误对照表与最小请求定位法 |
| 2026-09-22 | v1.0 | 首次发布：4xx / 5xx 状态码速查表 |