LLMGateway

Appearance

错误处理 ​

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

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

上游服务返回有意义的错误体时，网关可能保留上游 HTTP 状态码及 JSON 或纯文本错误内容；过大的上游错误正文可能被丢弃并改为标准化错误。客户端应优先判断 HTTP 状态码，兼容错误体没有 error.message 的情况，不要把供应商错误文案当成稳定协议。

常见错误 ​

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

重试建议 ​

  • 对 429、502、503 可以使用指数退避重试。
  • 不要对明显的 400 参数错误、402 额度问题、403 权限/开通问题、501 未启用能力持续重试。404 也不要盲目循环重试；先判断模型是否在当前 Key 的 /v1/models 中，若已可见仍持续报错，联系平台排查渠道而非直接认定客户模型名错误。
  • 流式请求建议设置较长的客户端超时时间。

参数校验 ​

Chat Completions 请求至少需要：

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

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

模型名与客户端预设 ​

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

OpenAI-compatible API documentation.

LLMGateway