错误码参考

API 返回的错误遵循统一的 JSON 格式，包含错误类型、错误码和详细信息。

错误响应格式

标准 API 端点（/api/v1/*）统一返回以下格式：

{
  "error": {
    "type": "rate_limit_error",
    "code": 42901,
    "message": "请求频率超限"
  }
}

Gateway 端点（/v1/*）为兼容各 SDK，采用对应的错误格式：

适用于 POST /v1/chat/completions、POST /v1/embeddings、GET /v1/models

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "model is required",
    "param": null
  }
}

适用于 POST /v1/messages

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}

错误码	类型	描述	处理建议
40000	invalid_request_error	请求参数错误	请求体格式不正确或缺少必要参数。请检查 JSON 格式和必填字段。
40100	authentication_error	未认证	请求未携带认证信息。请在 Header 中添加 Authorization: Bearer sk-your-api-key。
40300	invalid_request_error	无权限	当前 API Key 没有访问该资源的权限。请检查套餐和权限配置。
40400	not_found_error	资源不存在	请求的资源不存在。请检查 URL 路径和参数。
42900	rate_limit_error	请求频率超限	已超过全局速率限制。请降低请求频率。
50000	server_error	内部错误	服务端发生未预期的内部错误。请稍后重试或联系技术支持。

错误码	类型	描述	处理建议
40101	authentication_error	API Key 无效	提供的 API Key 不存在或已失效。请在控制台重新生成 Key。
40102	authentication_error	账户已冻结	账户因违规或其他原因被冻结。请联系客服。
40103	authentication_error	JWT 无效或已过期	登录会话已过期，请重新登录。

错误码	类型	描述	处理建议
40002	invalid_request_error	无效的统计周期参数	usage 统计接口的 period 参数不合法。可选值：today、week、month。
40003	invalid_request_error	不支持的支付渠道	请求的支付渠道不可用。目前支持 alipay 和 wechat。
40201	quota_exceeded	余额不足	账户余额不足以支付本次请求。请充值后再试。
40410	not_found_error	充值订单不存在	查询的充值订单号不存在。请确认订单号是否正确。
40411	not_found_error	发票不存在	查询的发票记录不存在。请确认发票 ID 是否正确。

错误码	类型	描述	处理建议
40401	not_found_error	API Key 不存在	操作的 API Key 已被删除或不存在。

错误码	类型	描述	处理建议
42901	rate_limit_error	请求频率超限	已超过 API Key 的 RPM/TPM/TPD 限制。请降低请求频率或升级套餐。
42902	rate_limit_error	Key 额度超限	当前 API Key 的 Token 配额已用完。请充值或创建新 Key。
42910	rate_limit_error	短信发送过于频繁	验证码发送间隔过短，请等待 60 秒后重试。

错误码	类型	描述	处理建议
50001	server_error	上游模型服务异常	上游模型提供商暂时不可用。系统会自动重试其他渠道，请稍后再试。
50002	server_error	无可用渠道	所有上游渠道均不可用。请联系技术支持。
50004	server_error	支付回调验签失败	支付平台回调签名验证失败，可能存在伪造请求。
50005	server_error	支付渠道通信异常	与支付平台通信失败。请稍后重试或联系技术支持。

业务错误码通过 code / 100 映射为 HTTP 状态码。例如错误码 40101 → HTTP 401。

400请求参数错误 (40000-40199)

401认证失败 (40100-40119)

402余额不足 (40201)

404资源不存在 (40400-40419)

429频率限制 / 配额超限 (42900-42919)

500服务端错误 (50000-50099)