集成/错误处理与重试

生产环境下的重试与幂等实践建议。

错误处理与重试

建立稳定的重试策略，确保 UniGateway 接入在高可用场景下保持正常服务。

前置条件

已完成基础接口联调
已建立请求日志记录机制

失败处理原则

区分请求校验错误（4xx）和临时性错误（429、5xx）
仅对临时性错误执行重试
为每个模型和任务设置封顶重试预算
记录每次尝试，保证回退行为可审计

HTTP 状态码处理

状态码	含义	处理方式
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
最终用户可见结果

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