错误码

HTTP 状态码

状态码	名称	说明
200	OK	请求成功
400	Bad Request	请求参数错误，如缺少必填字段、格式不合法
401	Unauthorized	API Key 无效或缺失
403	Forbidden	余额不足、Key 已被禁用、或无权访问该模型
404	Not Found	请求的端点或模型不存在
413	Payload Too Large	请求体过大，超出限制
429	Too Many Requests	请求频率超限
500	Internal Server Error	服务端内部错误
502	Bad Gateway	上游服务返回异常
503	Service Unavailable	服务暂时不可用
529	Overloaded	上游模型服务过载

错误响应格式

Anthropic 格式

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: field is required"
  }
}

OpenAI 格式

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Gemini 格式

{
  "error": {
    "code": 400,
    "message": "Invalid value for 'contents'",
    "status": "INVALID_ARGUMENT"
  }
}

常见错误

401 — API Key 无效

原因： API Key 错误、过期或未传递。

排查：

1. 确认 Key 以 sk- 开头，无多余空格
2. 确认 Key 未被在控制台禁用或删除
3. 确认请求头格式正确（Anthropic 用 x-api-key，OpenAI 用 Authorization: Bearer）

403 — 余额不足

原因： 账户余额耗尽。

排查：

1. 登录控制台查看余额
2. 余额 ≤ 0 时所有请求会被拦截
3. 充值后立即恢复，无需重启客户端

403 — 无权访问该模型

原因： 当前 API Key 未关联到包含该模型的渠道。

排查：

1. 联系管理员确认该模型已加入渠道
2. 确认你的 Key 所属用户组已开启对应模型

429 — 请求频率超限

原因： 短时间内请求过多，触发速率限制。

排查：

1. 降低请求频率
2. 等待一段时间后重试
3. 如有高并发需求，联系管理员调整限流配置

500 / 502 / 529 — 上游服务异常

原因： 上游模型提供商（Anthropic / OpenAI / Google）服务异常或过载。

排查：

1. 稍后重试
2. 尝试切换到其他模型
3. 529 通常为高峰期过载，等待几分钟后重试

400 — 请求参数错误

原因： 请求体格式不正确，如缺少必填字段、类型错误等。

排查：

1. 检查 model 字段是否为支持的模型名称
2. 检查 messages 数组格式是否正确
3. 检查 max_tokens 是否为正整数
4. 参考对应 API 文档确认参数格式：
   • Anthropic API
   • OpenAI API
   • Google Gemini API