错误处理
结合 HTTP 状态、协议错误体与 Request ID 定位失败。
读取错误响应#
网关生成的 OpenAI 兼容 HTTP 错误通常包含 error.message、error.type 和 error.code。上游错误会做规范化；Anthropic 与 Gemini 原生请求使用各自协议的错误结构。不要假定所有端点共享同一错误类型字符串。
网关参数错误示例
{
"error": {
"message": "model is required",
"type": "proxy_error",
"code": 400
}
}| 状态 | 排查方向 | 处理建议 |
|---|---|---|
| 400 | 缺少 model、字段无效或协议能力不支持 | 修正参数；确认上游支持该能力 |
| 401 / 403 | 无效或缺失密钥、scope、模型/IP 策略等 | 检查密钥状态和授权；缺少密钥可能返回 403 |
| 404 | 公开模型没有可路由映射 | 用模型列表确认名称，并联系管理员 |
| 429 | 密钥速率、并发、Token、配额或上游限流 | 读取 Retry-After；释放并发或调整额度 |
| 5xx | 上游失败、超时或内部服务不可用 | 记录 Request ID，使用有上限的退避重试 |
携带 Request ID 排查#
HTTP 响应的 X-Request-Id 可关联用量、审计和服务日志。遇到问题时保留状态码、公开模型、发生时间、错误摘要与该 ID，通过控制台「运营监控」或工单定位。
网关没有为任意代理生成请求提供通用幂等去重。重试可能产生新生成和新用量；已收到部分流式输出时不会自动重放。