错误处理与重试
建立稳定的重试策略，确保 UniGateway 接入在高可用场景下保持正常服务。
前置条件
- 已完成基础接口联调
- 已建立请求日志记录机制
失败处理原则
- 区分请求校验错误（4xx）和临时性错误（429、5xx）
- 仅对临时性错误执行重试
- 为每个模型和任务设置封顶重试预算
- 记录每次尝试，保证回退行为可审计
HTTP 状态码处理
Example request
Run it in your stack
Pick the SDK style that matches your app and copy the snippet directly into your project.
from openai import OpenAI
client = OpenAI(api_key="<YOUR_UNIGATEWAY_API_KEY>", base_url="https://api.unigateway.ai/v1")
# implement retry with exponential backoff for 429/5xx| 状态码 | 含义 | 处理方式 |
|---|---|---|
| 400 | 请求参数错误 | 修正参数，不直接重试 |
| 401 | 鉴权无效或缺失 | 检查 API Key 和请求头 |
| 402 | 余额不足 | 触发充值或告警流程，暂停重试 |
| 403 | 无权限 | 检查账号权限或访问策略 |
| 404 | 资源不存在 | 检查路径和模型 ID |
| 429 | 触发限流 | 指数退避 + 抖动重试 |
| 5xx | 服务或上游异常 | 退避重试；超预算后切换回退模型 |
401、403、402 比例升高时立即升级处理，重试无法修复账号状态。
退避参数
| 参数 | 值 |
|---|---|
| 初始延迟 | 300ms |
| 倍率 | 2x |
| 最大延迟 | 8s |
| 单模型最大重试次数 | 3 |
超过预算后切换到回退链中的下一个模型。
按接口族处理
Chat 与 Responses
- 对
429和5xx在同模型内做封顶退避重试 - 重试预算耗尽后切换回退模型
- 流式和非流式请求分开统计
流式输出
- 已有部分 token 被用户消费时，视为已产生用户可见结果
- 流中途断开时开启新的请求追踪，不伪装为同一次响应
- 流中断率独立监控
模型发现（GET /v1/models）
- 模型调用返回
404时不盲重试，先刷新模型列表 - 模型列表可短缓存，发版或目录变更后立即失效
异步任务
- 创建任务时保守重试，避免重复创建作业
- 重新提交同一业务动作前，先查询已有任务 ID
- 建议调用方保留自己的关联 ID
重试预算
| 接口族 | 重试预算 | 预算耗尽后的动作 |
|---|---|---|
chat.completions / responses | 每模型最多 3 次 | 切换下一个模型 |
| 流式聊天 | 无用户可见 token 时允许 1 次重连 | 开启新的请求追踪 |
GET /v1/models | 短时间小爆发重试 | 持续失败时上报降级状态 |
| 异步任务创建 | 最多 1-2 次 | 创建新任务前先查询或对账 |
| 异步任务轮询 | 可多次轮询，频率降低 | 到达总超时后停止 |
幂等处理
| 场景 | 策略 |
|---|---|
| 非流式文本生成 | 完整响应前失败可安全重试 |
| 流式输出 | 部分结果视为已消费，重试时创建新的请求追踪 |
| 状态型或异步接口 | 设计幂等键策略，避免重复副作用 |
升级规则
出现以下情况时立即升级处理：
401、403、402比例升高- 一个模型家族异常而其他家族正常，优先怀疑路由或上游局部故障
- Fallback 使用率异常飙升
可观测性
每次尝试至少记录：
- 请求时间
- 模型 ID
- 接口路径
- 状态码
- 重试次数
- 延迟
- 上游错误摘要
建议补充：
- 当前在回退链中的位置
- 是否为流式请求
- 任务 ID 或调用方关联 ID
- 最终用户可见结果