多语言 SDK 的错误类型映射
同一个后端错误,在 Python 里是 APIStatusError,在 Go 里是 *APIError,在 Node 里是 APIError。不统一错误语义,重试逻辑就会各写各的。
先按状态码,再按错误码
先判断 HTTP 状态码(429/5xx 可重试),再判断业务错误码(额度不足、模型不存在不可重试)。两层判断的顺序不能反。
对应到网关:401 多半是 Key 本身错误、过期或被撤销;403 多半是分组不允许访问目标模型,或者上游凭据失败。
把两者混为一谈,会让你往完全错误的方向查。
把重试逻辑抽成一层
在 SDK 之上包一层统一的调用函数,所有业务代码都走它。这样重试策略只需要改一处。
对 429 和 5xx 做指数退避重试,对 4xx 直接失败。
并且要给重试设总次数上限,否则在一个持续故障的上游上会把问题放大。
错误信息要保留原始 body
网关的错误体里通常包含结构化的 code 和 message。包装成统一异常时,别把 body 丢掉。
所以排障的第一步永远是把 GET /v1/models 的返回拿出来对着看。
看客户端收到的最后一个 SSE 事件是什么——如果是明确的 error 事件,说明网关做了正确的错误上报;如果是戛然而止,那就是真的断了。
错误日志要带 request_id
统一异常里带上 request_id,排查时可以直接去日志系统定位,不用靠时间戳猜。
当用户说「今天特别慢」的时候,你需要的东西不是一堆日志,而是一张能一眼看出哪个模型在降级的表。
一个合格的状态看板至少要区分四种状态:operational(正常)、degraded(成功但慢或多渠道部分失败)、failed(全部探测失败)、unknown(数据不足)。
实操:带指数退避的重试封装,只对真正可重试的错误重试。
这套封装在 Go 和 Node 里写法不同,但分层思路是一样的。
import random, time
from openai import OpenAI, APIStatusError
client = OpenAI(api_key=API_KEY, base_url="https://aiminis.info/v1")
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_retry(fn, attempts=3):
for i in range(attempts):
try:
return fn()
except APIStatusError as e:
if e.status_code not in RETRYABLE or i == attempts - 1:
raise
time.sleep((2 ** i) + random.random())
# 4xx(参数错、额度不足、模型不存在)不该重试,换渠道也一样失败。
几个容易踩的坑
- 跳过
GET /v1/models,直接猜模型名。 - 把 401 和 403 当成同一类错误去查。
- 没分清 429 是上游限的还是自己限的。
- 出问题时没有最小复现脚本,只能在业务代码里盲改。
小结
把可观测性做在前面,后面所有的优化才有依据。
文中的配置和示例都能在 https://aiminis.info/ 直接跑一遍,接入文档在 https://aiminis.info/docs/api-integration。
- 点赞
- 收藏
- 关注作者
评论(0)