401 / 403 / 429 常见错误码排查

本章节汇总了调用 API 时可能遇到的常见 HTTP 状态码及解决方案。

1. 401 Unauthorized (未授权)

现象：提示 Incorrect API key provided 或 Invalid token。
排查步骤：
1. 确认 API Key 是否完整复制（包含 sk- 前缀）；
2. 确认在 CC Switch 或客户端中是否启用了正确的服务商；
3. 登录控制台确认该 Key 是否处于启用状态。

2. 403 Forbidden (余额不足 / 权限受限)

现象：提示 Insufficient balance 或 Token quota exceeded。
排查步骤：
1. 登录控制台查看账户余额是否充足；
2. 若该 Key 单独设置了子额度，确认子额度是否已达上限；
3. 确认 Key 分组权限是否包含了当前请求的模型。

3. 429 Too Many Requests (频率限制)

现象：提示 Rate limit exceeded。
排查步骤：短时间内高频并发超出限制，稍等片刻重试，或在代码中引入指数退避重试机制。

4. 404 Not Found (路径错误)

现象：提示 Route not found 或 404 page not found。
排查步骤：确认 OpenAI 客户端使用 /v1，会自动补全路径的工具使用裸域名；不要把 /v1 重复拼接。

5. 504 Gateway Timeout (网关超时)

现象：在调用超长思考与复杂推理模型（如 deepseek-v4-pro、claude-opus-5、claude-opus-4-8、o1）时长时间无响应后断开。
排查步骤：强烈推荐开启流式输出 (stream=true)，只要模型生成思考字符即可保持长连接稳定。