多语言 SDK 的错误类型映射

举报
Rolle 发表于 2026/11/15 18:15:21 2026/11/15
【摘要】 同一个后端错误,在 Python 里是 APIStatusError,在 Go 里是 *APIError,在 Node 里是 APIError。不统一错误语义,重试逻辑就会各写各的。

同一个后端错误,在 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。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。