常见错误排查¶
通用排查思路¶
遇到任何工具 / SDK 报错，先用一条 curl 把「Key 问题」和「工具配置问题」分开：
curl https://api.lowcostaiapi.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'
- curl 成功、工具失败 → 问题在工具配置（Base URL、模型名、环境变量）；
- curl 也失败 → 按下表对照状态码。
按状态码排查¶
401 Unauthorized — Key 问题¶
- Key 复制不完整或带了多余空格 / 换行；
- Key 在 令牌管理 中被禁用或已删除；
- 环境变量没生效（改完配置文件忘了
source，或 Windows 没重开终端）； - 工具里残留了官方账号的旧凭证，覆盖了你的配置（Claude Code 检查
~/.claude，Codex 检查~/.codex/auth.json）。
403 Forbidden — 余额或权限问题¶
- 账户余额不足 → 充值；
- 该 Key 的额度上限已用尽 → 令牌管理里调整额度；
- 套餐已过期 → 检查钱包页的套餐有效期。
404 Not Found — 路径或模型问题¶
- Base URL 路径不对：OpenAI 协议要带
/v1，Anthropic 原生协议不带（见 接入地址总览）； model填了平台不支持的 ID → 去 模型列表 复制正确的；- 地址里有拼写错误 / 多余的斜杠。
429 Too Many Requests — 频率限制¶
- 降低并发请求数；
- 客户端加指数退避重试（注意重试本身也会产生消耗）；
- 长期高并发需求请 联系我们。
5xx — 服务端 / 通道波动¶
- 稍后重试；
- 切换到其他可用模型（如 Gemini 波动时切 Claude / OpenAI）；
- 持续出现请查看控制台公告或联系客服。
连接超时 / SSL 错误¶
- 检查本地网络与代理设置（部分代理软件会拦截 API 请求）；
- 公司 / 校园网络可能有防火墙限制，换个网络试试；
- 确认地址是
https://开头。
按现象排查¶
| 现象 | 可能原因 | 解法 |
|---|---|---|
| 环境变量设置后不生效 | 改错文件 / 没重载 | zsh 用 ~/.zshrc，bash 用 ~/.bashrc，改完 source；Windows 重开终端 |
| 工具能连上但回复走的是官方账号 | 旧登录凭证优先级更高 | 退出工具内登录（/logout），只保留环境变量配置 |
| 消耗异常偏大 | 上下文过长 / 模型过重 / 自动重试 | 看日志逐笔核对；任务拆小；及时清上下文 |
| 中文项目路径下报错（Windows） | 旧版 Git 的 cygpath 问题 | 升级 Git 到 2.40+：winget upgrade Git.Git |
| npm 安装权限不足 | 全局目录无权限 | npm config set prefix '~/.npm-global' 后重装 |
还是解决不了？¶
带上以下信息 联系我们，能最快定位问题：
- 完整的报错信息（截图或文本）；
- 使用的工具 / SDK 及版本；
- 出问题的大致时间点（方便我们查服务端日志）；
- 不要直接发送完整的 API Key。