跳到主要内容
Ainfix
注册账户

常见错误与排障诊断

在调用 API 遇到报错时，可以通过返回的 HTTP 状态码与响应体中的 error.message 快速定位原因。

常见 HTTP 状态码清单​

1. 401 Unauthorized (认证失败 / 无效密钥)​

典型响应：

{
  "error": {
    "message": "Incorrect API key provided: sk-***",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

排查清单：

  • 检查请求头 Authorization: Bearer sk-... 格式是否规范，密钥前后是否有误复制的空格或换行。
  • 在「控制台 - API 密钥」中检查该令牌是否已被禁用或删除。
  • 确认当前使用的令牌是否设置了 IP 白名单或限定了模型范围。

2. 429 Too Many Requests / Insufficient Quota (超额 / 频控)​

可能原因与解决方案：

  1. 账户或令牌额度耗尽（Insufficient Quota）：
    • 检查「个人控制台」总账户余额。
    • 检查当前使用的 API Key 是否设置了独立的额度上限且已达上限。
  2. 请求频率或并发超限（Rate Limit Exceeded）：
    • 客户端短时间内发起突发高并发请求。
    • 建议在客户端代码中实现指数退避重试（Exponential Backoff）。如需更高企业并发，请在支持中心提交工单。

3. 404 Model Not Found (模型不存在)​

可能原因与解决方案：

  • 请求体中的 model 字段名称拼写有误（如将 gpt-4o 误写为 gpt4o）。
  • 确认该模型在平台当前处于可用状态（可在 模型广场 查看）。

4. 500 / 502 / 504 Gateway Error (上游通道异常)​

可能原因与解决方案：

  • 上游模型官方提供商（如 OpenAI、Anthropic）发生服务中断或网络波动。
  • Ainfix 内置了多通道智能重试与自动 Failover 机制，绝大部分网络抖动会在平台内部完成无感转移；若大范围持续报错，请关注平台状态或在支持中心发起工单。