上游报错码到用户报错的映射表

举报
Rolle 发表于 2026/11/15 18:01:42 2026/11/15
【摘要】 网关应该把上游的各种错误翻译成一套稳定的错误码。用户和监控依赖的是这套码,而不是上游原文。

网关应该把上游的各种错误翻译成一套稳定的错误码。用户和监控依赖的是这套码,而不是上游原文。

错误码要稳定,文案可以变

message 是给人看的、会变;code 是契约、不能变。日志和监控应该基于 code。

对应到网关:401 多半是 Key 本身错误、过期或被撤销;403 多半是分组不允许访问目标模型,或者上游凭据失败。

看客户端收到的最后一个 SSE 事件是什么——如果是明确的 error 事件,说明网关做了正确的错误上报;如果是戛然而止,那就是真的断了。

映射表要覆盖全部可切换原因

401/403/429/502/503/504、凭据刷新失败、拨号失败——这几种在上游层可能是完全不同的报文,但映射到网关层应该收敛到少数几个语义。

网关在一次请求里最多尝试三个不同的渠道,这个上限是为了避免「雪崩放大」——上游全挂时,每个请求都试完全部渠道会把压力成倍反弹回去。

同时还有更严格的门槛:只有明确的暂时性故障(401/403/429/502/503/504、OAuth 刷新失败、连接拨号失败)才允许切换。

流式错误要用事件表达

流已经开始之后没法改 HTTP 状态码,只能在 SSE 里发一个 error 事件。客户端必须识别它,否则会把半个回答当成完整结果。

流式场景下,工具参数是分片到达的,网关需要在内存里把它们拼接成完整 JSON。

这里必须设上限:单个请求的工具参数总量、工具调用个数、以及非流式响应体大小,都要有硬顶。

本地拒绝和上游失败要分开

额度不足、模型不存在、Key 无效是本地直接拒绝的,根本没到上游。它们在成功率统计里也不该算成上游故障。

如果没有 Key 级限流,一个写错循环的脚本就能把共享池子的额度全部吃掉,其他用户跟着受影响。

评估套餐的时候,额度看总消耗、并发看峰值,两者要分开算。

实操:带指数退避的重试封装,只对真正可重试的错误重试。

把状态码和错误体一起记录,才能做后续的聚合分析。

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/ 这个自建的 API 网关,支持 OpenAI 与 Anthropic 双协议接入,还有公开的模型健康看板 https://aiminis.info/model-health 可以先看看状态。

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

评论(0)

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

全部回复

上滑加载中

设置昵称

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

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

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