错误、限制与重试
集中处理客户端安装、配置、状态码和重试问题。
安装
- 安装后提示命令不存在：关闭并重新打开终端，再确认 npm 全局可执行目录已加入
PATH。 - 客户端形态不同：OpenCode CLI、桌面版和本地 Web 使用同一份配置；Kimi Web 随 CLI 提供。
- VS Code 插件未读取配置：确认安装的是官方插件，保存配置后完全退出并重新打开 VS Code。
配置与协议
配置中的 Base URL、API Key 和模型名以对应客户端指南为准。
- Codex 使用 OpenAI Responses，Base URL 以
/v1结尾，wire_api为responses。 - Claude 使用 Anthropic Messages，Base URL 不带
/v1；客户端会请求/v1/messages。 - 其他 OpenAI Compatible 客户端使用带
/v1的地址。 - Key 必须直接写入对应客户端配置或设置界面；不要同时保留冲突的旧 Key、环境变量或 Provider。
客户端限制
- Cursor 的自定义 API Key、Base URL 和指定模型需要 Cursor Pro；免费版和
Auto模型不能用于配置或验证自定义中转。 - CCSwitch 只负责写入和切换 Provider，不是独立 Agent；最终回复应在 Codex 或 Claude 中确认。
- 图形客户端不同版本的菜单名称可能略有变化，应进入模型、Provider 或 API Key 设置页，不要在账户登录页填写中转参数。
HTTP 状态
| 状态 | 常见原因 | 处理 |
|---|---|---|
400 | 请求正文错误、字段冲突或协议不匹配 | 修正配置或请求，不原样重放 |
401 | API Key 缺失、格式错误或未被客户端读取 | 重新保存 Key 并重启客户端 |
402 | 可用余额不足 | 检查余额并充值 |
403 | Key 无效、账户限制、CIDR、消费或 API 地址限制 | 核对 Key、账户策略和地址 |
404 | Base URL 后缀错误、操作路径错误或模型不存在 | 按协议修正地址并核对公开模型名 |
405 | 当前协议或操作不受支持 | 选择客户端支持的协议与操作 |
413 | 请求正文或文件超过限制 | 缩小输入或文件 |
429 | RPM、并发或账户容量限制 | 等待后按有界退避重试 |
502 / 503 / 504 | 服务暂时不可用或响应超时 | 稍后重试 |
审慎重试
超时或断开连接后，原调用仍可能已经完成。重试前：
- 确认原请求的状态。
- 判断是否能接受重复输出与费用。
- 仅对
429和临时依赖故障实施有界退避。 - 把重试视为新的独立调用。