故障排查

推荐排查顺序

1. 停止客户端自动重试和并发任务。
2. 记录北京时间、接口、模型、状态码和请求 ID。
3. 用 /v1/models 验证网络、TLS 和密钥。
4. 发起不带工具、附件和实验参数的最小请求。
5. 到控制台使用记录确认请求是否到达 FreedomZ AI。
6. 根据状态码处理，不要通过轮换账号规避错误。

状态码速查

现象	常见原因	首要处理
400 / invalid request	JSON、字段或参数不兼容	缩减到最小请求，核对必填字段
401 / invalid api key	Key 错误、撤销、过期或认证头错误	立即停止重试，检查 Key
403 / forbidden	内容、账户、分组、地区或上游策略拒绝	停止任务，不要切换 Key 连续重试
404 / 405	Base URL 或接口路径错误	检查是否重复或缺少 /v1
429	并发过高、限流或资源暂不可用	降低并发，指数退避
余额不足 / quota	账户余额、Key 额度或有效期不可用	核对余额、Key 和订单
model not found	模型 ID 错误或分组不支持	重新查询 /v1/models
5xx	网关或上游临时异常	保留请求 ID，有限重试
客户端有回复、使用记录为空	请求走了官方账号或其他 Provider	检查 Provider 和 Base URL
长时间无响应	上游推理、流式读取、代理或超时配置问题	先用最小请求区分链路与推理

先做最小请求

确认 DNS、TLS 和密钥：

curl -i https://freedomz.cn/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

如果模型列表成功，再测试不带工具、附件和实验参数的最小对话请求。

401 认证失败

• 确认请求头格式为 Authorization: Bearer ...。
• 检查密钥是否有空格、换行或被撤销。
• 检查 Key 是否过期、额度是否可用。
• 不要连续切换多个密钥或账号重试同一请求。
• 停止自动任务并联系支持检查账户状态。

401 / 403 必须停止

第一次出现 401 或 403 后，当前自动任务应立即终止。不要让客户端把相同内容 依次转发到其他密钥或账号，这可能扩大账户风控影响。

403 请求被拒绝

• 检查请求是否触发内容政策、上游安全策略或地区限制。
• 不要通过改写、编码、分段或提示注入规避安全机制。
• 删除敏感内容后重新评估业务用途。
• 对误判提交脱敏后的请求结构和请求 ID。

400、404 或路径错误

• 检查 OpenAI Compatible Base URL 是否为 https://freedomz.cn/v1。
• 客户端自动追加 /v1 时应改填 https://freedomz.cn。
• Claude Code 的 ANTHROPIC_BASE_URL 使用 https://freedomz.cn。
• 删除厂商专属或实验参数后重新测试。
• 确认使用的接口与客户端协议匹配。

典型错误路径是 /v1/v1/chat/completions，说明 /v1 被重复拼接。

429 请求过多

• 降低并发和请求频率。
• 使用指数退避，例如 2、4、8、16 秒，设置最大次数。
• 避免多个工作进程同时立即重试。
• 检查单个任务是否形成循环调用。

5xx 或连接中断

• 保留请求 ID、时间和模型名称。
• 对幂等请求进行有限重试。
• 工具调用、支付或其他可能产生副作用的请求，重试前先确认是否已执行。
• 流式连接中断时，不要把已生成内容和完整请求无条件重复提交。

余额不足或模型不存在

余额不足时依次检查：

1. 控制台余额是否可用；
2. Key 自身额度和有效期；
3. 订单是否已完成；
4. 当前分组是否可用。

model not found 时不要猜模型名称。使用同一把 Key 调用 /v1/models，从 data[].id 原样复制。

使用记录为空

客户端能正常回复但 使用记录 没有新数据，说明 请求大概率没有到达 FreedomZ AI：

• 检查客户端是否仍在官方账号登录模式；
• 检查当前 Provider 是否为 FreedomZ AI；
• 检查 Base URL 是否仍是旧地址；
• 启用 CCSwitch 配置后重新启动客户端；
• VS Code 扩展需要重新加载窗口。

请求很慢

• 用 /v1/models 区分网络问题和模型推理耗时。
• 检查客户端代理、DNS、TLS 和读取超时。
• 降低输入长度、工具数量和并发。
• 不要因为单个请求慢而无限并行提交同一任务。
• 流式请求有首字节但后续慢，通常与模型推理或上游资源有关。
• /v1/models 也明显变慢时，再检查本地网络、DNS 和代理。

提交支持信息

请提供：

• 北京时间和时区；
• 接口路径、模型、状态码；
• 请求 ID；
• 客户端和 SDK 版本；
• 是否流式、重试次数；
• 脱敏后的最小请求结构。

不要提交完整密钥、密码、Cookie 或包含个人敏感信息的完整提示词。