AI API 401、403、404、429 错误排查指南

先做四项基础检查

1. 确认 API Key 没有缺失字符或多余空格。
2. 确认 Base URL 与客户端追加路径的规则。
3. 从模型广场重新复制模型名称。
4. 确认令牌分组包含目标模型且账户余额充足。

401 Unauthorized

表示认证没有通过。常见原因是 Key 错误、令牌被禁用、请求头不是 Authorization: Bearer ...，或环境变量仍被旧 Key 覆盖。

curl https://apihalo.cn/v1/chat/completions \
  -H "Authorization: Bearer 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"测试"}]}'

403 或模型不可用

优先检查令牌所属分组是否包含目标模型。内部别名、大小写和后缀都可能影响匹配，不要自行缩写模型名。

404 Not Found

OpenAI 兼容接口通常使用 https://apihalo.cn/v1。如果客户端自动追加 /v1，则填写 https://apihalo.cn，避免形成 /v1/v1。

429 Too Many Requests

可能由请求过快、并发限制、渠道暂时繁忙或额度不足造成。降低并发并使用指数退避重试，同时检查账户余额和平台状态。

响应慢或超时

• 先查看 服务状态。
• 用最小 curl 请求排除客户端插件影响。
• 减少上下文长度和并发。
• 查看控制台日志中的实际状态码与耗时。