错误处理

LLMGateway 自身生成的错误通常使用 OpenAI-compatible error envelope：

{
  "error": {
    "message": "upstream service temporarily unavailable",
    "type": "upstream_error",
    "code": "502"
  }
}

上游服务返回有意义的错误体时，网关可能保留上游 HTTP 状态码及 JSON 或纯文本错误内容。客户端应优先判断 HTTP 状态码，并为无法解析 error.message 的情况保留原始错误摘要。

常见错误

HTTP 状态	含义	建议处理
400	请求参数不合法	检查 model、messages、tools、tool_choice 等字段
401	API Key 缺失或无效	检查 Authorization: Bearer ...
402	额度不足、预算超限或账户冻结	检查控制台余额和预算额度；若已充值仍报错，联系平台确认账户状态。注意 error.code 当前为状态码字符串（如 "402"），不区分具体原因，需结合 error.type（如 insufficient_quota）判断
403	当前租户未开通模型，或当前 API Key 不允许调用该模型	先到控制台模型广场开通模型，再检查 API Key 的模型限制
404	模型不存在或当前 Key 不可调用	使用 /v1/models 查询可用模型，确认模型 ID 大小写
429	请求过快或上游限流	稍后重试，必要时降低并发
501	接口或能力暂未启用	查看 接口兼容，改用已支持接口
502	上游服务暂时不可用	重试请求；持续失败时联系服务提供方
503	上游渠道暂无可用实例或模型配置不可用	短暂重试；持续失败时联系平台确认模型或渠道配置

重试建议

• 对 429、502、503 可以使用指数退避重试。
• 不要对明显的 400 参数错误、402 额度问题、403 权限/开通问题、404 模型不存在或 501 未启用能力持续重试。
• 流式请求建议设置较长的客户端超时时间。

参数校验

Chat Completions 请求至少需要：

• model：使用 /v1/models 返回的模型 ID。
• messages：非空数组，每条消息包含合法 role 和 content。
• max_tokens：如传入，必须大于等于 0。

Responses 请求至少需要 model 和 input，max_output_tokens 如传入也必须为正数。

模型名与客户端预设

部分客户端会预置或自动改写模型名，但这些名称不一定已在当前账号开通。不要根据厂商产品名猜测别名；请始终从 /v1/models 读取当前 API Key 实际可调用的模型 ID，并保持大小写不变。