API 故障排查
先收集四项信息
- 请求使用的接口类型：Chat、Responses 或 Anthropic；
- 模型广场复制的精确模型 ID；
- HTTP 状态码和脱敏后的错误正文；
- 控制台调用记录、发生时间和扣费结果。
不要在截图或日志中保留完整密钥、Authorization 请求头、Cookie 或用户数据。
注册、充值与余额
- 无法注册或登录：核对是否使用 API 站账号，而不是镜像站账号；用系统浏览器或无痕窗口做一次对比。
- 支付后余额未到账：核对支付渠道状态、钱包记录和到账时间，不要立即重复支付。
- 订阅状态不符：保存商品说明、订单号和钱包页脱敏截图，确认套餐起算时间及额度刷新规则。
- 余额存在但请求仍失败：继续按状态码排查，余额不代表密钥、分组和模型权限正确。
401 与 403：认证和权限
| 状态码 | 常见原因 | 处理 |
|---|---|---|
| 401 | 密钥缺失、错误、过期或已撤销 | 检查环境变量和密钥状态；不要把密钥发给他人 |
| 403 | 密钥分组或权限不含目标模型 | 核对密钥权限、分组和模型；必要时创建新的独立低额度密钥 |
不要用账号登录密码替代 API 密钥，也不要为排除 403 而把现有密钥直接扩大到无限额、全模型权限。
400 与 404：请求、路径和模型
| 状态码 | 常见原因 | 处理 |
|---|---|---|
| 400 | 请求格式、参数或接口类型错误 | 核对 Chat、Responses 或 Anthropic 类型、JSON 和必填字段 |
| 404 | 路径或模型不存在 | 从模型广场重新复制精确模型 ID，不猜接口路径 |
Chat 模型不能自动替代 Response 模型，Anthropic Messages 也不能直接照抄 Chat Completions 的请求格式。Base URL 是否包含 /v1 取决于客户端输入规则；不要在服务地址和客户端自动拼接中重复添加。
413、429、500 与 529：大小、额度和上游
| 状态码 | 含义 | 处理 |
|---|---|---|
| 413 | 请求过大 | 减少文件和上下文，Claude Code 可考虑 /compact |
| 429 | 速率或额度限制 | 停止重试，查看余额、限速和恢复时间 |
| 500 | 服务内部错误 | 保存请求时间和请求 ID，稍后重试 |
| 529 | 上游过载 | 降低并发、等待后再逐步恢复 |
多个模型同时出现 500 或 529 时先查看公告。连续快速重试会放大限速或上游压力，应降低并发并间隔测试。
客户端与本地环境
找不到 claude
- 确认 Node.js 为当前 LTS；
- 重新运行官方包安装命令；
- 打开新终端，执行
claude --version； - 检查 npm 全局可执行目录是否在
PATH。
Windows 还需要按 Claude Code 当前官方要求安装 Git for Windows，并确认 Git Bash 路径可访问。不要为了运行一个工具永久放宽整个系统的脚本策略。
模型更新后不可用
先更新客户端，再从模型广场复制当前 ID。Chat 模型不能自动替代 Response 模型；接口类型不匹配时，换模型名称也不能解决。
第三方客户端连接失败
确认客户端实际使用 Chat Completions、Responses 还是 Anthropic Messages；分别核对 Base URL、是否由客户端自动补 /v1、模型 ID 和该客户端的独立密钥。先在首次请求与验证中验证基础组合，再排查客户端特有设置。
历史脚本提示：API test failed
原稿曾建议在一键脚本测试失败后直接输入 y 继续。该做法会掩盖错误，现改为：停止脚本，检查来源和内容，单独验证 Base URL、密钥、接口类型与模型 ID。验证失败时不要继续安装。
问题上报
提供脱敏请求、状态码、请求 ID、时间、模型 ID、接口类型和客户端版本。完整密钥、密码、验证码和会话信息始终不提供。