集成指南/错误处理与重试

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

错误处理与重试

本指南给出 UniGateway 稳定接入时的实用重试策略。

失败处理原则

  1. 把请求校验错误和瞬时容量错误分开处理。
  2. 只有当错误具有临时性时才重试。
  3. 为每个模型、任务和用户动作设置封顶重试预算。
  4. 记录每一次尝试，保证 fallback 行为可审计。

HTTP 状态码处理建议

状态码含义建议动作
400请求参数错误修复请求，不要直接重试。
401鉴权无效/缺失修复 Key 或请求头，不要盲重试。
402余额不足触发充值/告警流程，暂停重试。
403无权限检查账号权限或访问策略。
404资源不存在检查路径、接口和模型 ID。
429触发限流指数退避 + 抖动重试。
5xx服务或上游异常退避重试，超预算后走回退模型。

按端点族处理

Chat 与 Responses 接口

  • 对 429 和 5xx 先在同模型内做封顶退避重试。
  • 重试预算耗尽后，再切到下一个回退模型。
  • 流式和非流式请求要在追踪系统中分开看待。

流式接口

  • 一旦已有部分流输出被用户消费，就视为已经产生用户可见结果。
  • 如果流在中途断开，应开启新的请求追踪，而不是伪装成同一次响应。
  • 流中断率要单独监控，它和普通 JSON 请求失败不是一类问题。

模型发现接口

  • 模型调用出现 404 时，不要直接盲重试；先刷新 GET /v1/models。
  • 模型列表可以短缓存，但在发版或模型目录变更后应立即失效。

异步任务接口

  • 创建任务的重试要更保守，避免重复创建作业。
  • 在重新提交同一业务动作前，先查询已有任务 ID。
  • 即使公开 API 没有一等幂等键，也建议调用方保留自己的关联 ID。

退避参数建议

  • 初始延迟：300ms
  • 倍率：2x
  • 最大延迟：8s
  • 单模型最大重试次数：3

超过预算后切换到回退链下一个模型。

推荐重试预算

端点族重试预算预算耗尽后的动作
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