上游报错码到用户报错的映射表
网关应该把上游的各种错误翻译成一套稳定的错误码。用户和监控依赖的是这套码,而不是上游原文。
错误码要稳定,文案可以变
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 可以先看看状态。
- 点赞
- 收藏
- 关注作者
评论(0)