错误处理

LLMGateway 使用 OpenAI-compatible 的错误响应格式。

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

常见错误

HTTP 状态	含义	建议处理
400	请求参数不合法	检查 model、messages、tools、tool_choice 等字段
401	API Key 缺失或无效	检查 Authorization: Bearer ...
403	当前租户未开通模型，或当前 API Key 不允许调用该模型	先到控制台模型广场开通模型，再检查 API Key 的模型限制
404	模型不存在或当前 Key 不可调用	使用 /v1/models 查询可用模型，确认模型 ID 大小写
429	请求过快或上游限流	稍后重试，必要时降低并发
501	接口或能力暂未启用	查看 接口兼容，改用已支持接口
502	上游服务暂时不可用	重试请求；持续失败时联系服务提供方
503	上游渠道暂无可用实例或模型配置不可用	短暂重试；持续失败时联系平台确认模型或渠道配置

重试建议

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

参数校验

Chat Completions 请求至少需要：

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

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

Cursor 模型名

Cursor 对 claude-* 模型名有内置校验。使用 OpenAI-compatible 接入时，建议选择 opus-4-7 这类兼容别名。