API 调用失败排查：401 / 403 / 429 / 余额不足
Claude Code、Codex、Cursor、Dify、Cherry Studio、OpenAI SDK 或自研程序调用失败时，先用这一页判断该查 Token、base_url、模型名、日志，还是查余额和充值。
一句话答案：不要一看到失败就先充值。先看错误码和控制台日志：401 多半是 Token 或 Authorization；403/1010 多半是地址、请求路径、客户端配置或权限；429 多半是频率、并发或模型临时限制；余额不足才进入充值流程。
按报错类型快速定位
401 / Invalid token / unauthorized
先检查 Authorization: Bearer sk-完整Token、Token 是否复制完整、是否使用了旧 Key、客户端是否保存成功。
403 / 1010 / Forbidden
先检查 base_url、请求路径、User-Agent、客户端是否真的走 OpenAI 兼容入口，再看控制台日志。
429 / rate limited
先降低并发，用短请求验证；如果是特定模型，先换低延迟或备用模型确认链路是否可用。
余额不足 / insufficient quota
确认当前账号、Token 所属账号、钱包余额和充值到账账号一致，再从控制台充值当前账号。
日志没有请求
通常说明请求没进到当前账号，先查客户端的 base_url、API Key、环境变量、代理和是否重复拼了 /v1。
model_not_found / 模型名错误
确认模型名用的是实际 ID，不是展示名；先用文档或控制台推荐模型跑一个最小请求。
推荐排查顺序
在控制台打开令牌管理，确认当前客户端用的是同一个账号下的 Token。
确认 base_url 是
https://api.token-ciyuan.com/v1，不要写成首页、充值页或重复 /v1/v1。用最小请求测试一个短回复，先不要跑长文档、Agent、多轮工具调用或图片任务。
打开使用日志，看请求是否进入当前账号；没有日志就先改客户端配置，有日志再按错误码处理。
确认模型名、余额、并发和调用方式，再决定是否充值、换模型或继续排查客户端。
最小验证请求
curl https://api.token-ciyuan.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-完整Token" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "reply ok"}],
"max_tokens": 16
}'如果这个请求在控制台日志里能看到，再把同样的 Token、base_url 和模型名填回 Claude Code、Cursor、Dify 或你的程序里。
什么时候该充值
只有在控制台余额不足、日志明确提示余额不足，或你已经跑通最小请求并准备扩大真实调用时，再进入充值。充值前先确认页面显示的到账账号和当前 Token 所属账号一致。
排障时不要把完整 Token 发给任何人。需要协助时，提供请求时间、错误码、模型名、客户端名称、控制台是否有日志即可。