Claude Code API Key 无法使用怎么办：401、403、429、余额不足排查
Claude Code、Codex、Cursor、OpenClaw、Dify 或自研代码 Agent 调用 OpenAI 兼容接口时，如果遇到 401、403/1010、429、余额不足或 model_not_found，可以先按下面顺序排查。
直接答案：先不要反复重试。401 先查 Token；403/1010 先查请求地址、请求头和新 Token；429 先查请求频率和模型可用性；余额不足先查钱包和到账账号；model_not_found 先查模型名。修正后用一个短请求验证，并在控制台日志里确认。
按错误码快速判断
| 提示 | 优先检查 | 下一步 |
|---|---|---|
| 401 Invalid Token / unauthorized | Token 是否完整、有效、填在正确位置 | 重新复制 Token，确认 Authorization: Bearer sk-完整Token |
| 403 Forbidden / 1010 | base_url、User-Agent、请求头、客户端是否保存了旧配置 | 确认接口地址为 https://api.token-ciyuan.com/v1，必要时新建 Token 测试 |
| 429 rate limited | 调用频率、并发、模型临时状态 | 降低并发、稍后重试，或切换备用模型先跑通链路 |
| insufficient_quota / 余额不足 | 登录账号、Token 所属账号、钱包余额、充值到账账号 | 进入钱包给当前账号充值，再用同一 Token 短请求验证 |
| model_not_found / 模型不可用 | 模型名是否来自控制台或文档 | 复制可用模型名，避免使用展示名或拼写错误 |
推荐排查步骤
在词元 API 控制台进入令牌管理，复制当前有效 Token。
确认 Claude Code 或代码 Agent 的 API Key 字段使用这个 Token，不要混用旧 Token。
确认 OpenAI 兼容接口地址填为
https://api.token-ciyuan.com/v1，不要重复写两个 /v1。确认模型名来自控制台或文档，例如不要把展示名、别名和实际模型 ID 混在一起。
发起一个很短的测试请求，先让它返回少量内容。
打开控制台使用日志。如果日志没有请求，继续查客户端配置；如果有请求，再按日志里的错误处理。
需要继续使用时，从钱包给当前账号充值，并确认到账账号与 Token 所属账号一致。
最小测试请求
如果工具支持 OpenAI 兼容接口，可以先用最小请求验证。关键是 base_url、Token、model 三项同时正确。
curl https://api.token-ciyuan.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-完整Token" \
-H "User-Agent: OpenAI/Python 1.0" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "reply ok"}],
"max_tokens": 16
}'不要把完整 Token 发到公开聊天、截图或代码仓库里。需要排查时，提供账号、请求时间、模型名、错误码和使用日志截图即可。
如果新建 Token 后还是失败
日志没有请求说明请求没有进入当前账号。重点查客户端是否仍在使用旧环境变量、旧配置文件、旧工作区设置，或请求地址是否填错。
日志有 401说明认证没有通过。重新复制完整 Token，确认请求头包含
Bearer 和一个空格。日志有 403/1010先换一个标准客户端或最小请求验证，确认 User-Agent、Authorization 和 base_url 都正常。
日志有 429先降低并发和请求频率，换短请求或备用模型验证，不要连续高频重试。
日志显示余额不足进入钱包查看余额和到账账号。余额属于登录账号，不是单独属于某个 API Key。
常见问题
401 和 403 有什么区别？
401 通常表示 Token 认证没有通过；403 通常表示请求被拒绝或请求形态不符合要求。两者都应先查 Token、请求头、base_url 和客户端配置。
429 是不是余额不足？
通常不是。429 更常见是调用太密或模型临时不可用。余额不足一般会直接提示余额或额度问题。
Claude Code 充值是给 API Key 充值吗？
不是单独给某个 API Key 充值。余额属于登录账号，API Key 使用这个账号的余额。充值前要确认到账账号和 Token 所属账号一致。
为什么建议 Claude Code 单独建 Token？
代码 Agent 通常会多轮读取、修改、检查和重试。单独 Token 更容易在日志里区分它的请求，排查也更清楚。
修好后怎么验证？
先发一个短请求，确认能返回内容；再进入控制台查看日志和余额变化。确认无误后，再运行更长的 Agent 任务。