AI / 排障

API 连不上:先分层,再改配置

同一句 timeout,可能卡在 DNS,也可能卡在出口被限速;分开测才知道该改哪。

四层定位密钥与限流可复现
本篇要点
  • 四层:解析 → 握手 → HTTP 状态 → 业务限流,逐层排除。
  • 不带 Key 先测连通,能立刻分清「网络不通」与「身份不对」。
  • 401 是身份,403 是地区或权限,429 是频率或额度。

四层定位

层怎么测正常表现异常含义
域名解析dig 或 nslookup 目标域名返回 A / AAAA 记录无记录:域名写错或被拦
TLS 握手curl -I https://端点返回 HTTP 响应头卡住或重置:SNI 被拦、出口被限
HTTP 状态看返回码2xx 或 401403 地区或权限,5xx 服务端
业务限流看 retry-after 与额度页无 429429:并发过高或额度用尽

顺序不能反。先查状态码的人,会把 DNS 问题当成密钥问题,反复重置 Key 也没有用。

不带 Key 先测一次

curl -sS -o /dev/null -w '%{http_code} %{time_starttransfer}\n' https://api.openai.com/v1/models

返回 401 说明网络完全通,只是没带密钥;返回 000 或长时间无输出,才是网络层的问题。这一步不需要账号,也不消耗额度,适合作为每次排障的第一条命令。

三个状态码怎么办

  • 401:密钥错、已撤销,或请求头里根本没带上;先确认变量名与是否被 shell 吞掉
  • 403:地区不支持、账号无权限,或出口被判定为代理;换出口比换 Key 有效
  • 429:并发或额度用尽,按响应头的 retry-after 退避,别原地重试

区分 403 与 429 有个笨办法:换一个完全无关的端点再试。所有端点都 403,是账号或地区;只有某一个 429,是那个接口的额度。

代理怎么设才生效

命令行工具普遍读 https_proxy 与 http_proxy,但读取时机不同:curl 每次请求都读,某些语言的 HTTP 库只在进程启动时读一次,容器里则完全不继承宿主的设置。装在 Docker 里跑的服务要单独传环境变量。

日志里看什么

只记三样就够:状态码、总耗时、错误类型。总耗时里再拆出连接时间与首字节时间,前者长是网络或代理的问题,后者长是对端在排队。把这三样存成一行 CSV,出问题时对比上一次正常的时间段,比问「是不是墙了」有用。

常见问题

能 ping 通但 API 不通,是什么问题?

多半是 TLS 或 HTTP 层被拦。ping 只证明 ICMP 可达,不证明 443 上的握手能完成。

换了 Key 还是 401?

先确认请求头真的带上了。常见的坑是复制时带了换行,或变量在子 shell 里没导出。

必须用代理才能调 API 吗?

看你所在网络到端点的可达性。先用不带 Key 的命令测一次,通了就不必额外配置。

429 一直不退怎么办?

退避时间按指数增长,同时把并发降下来。持续 429 说明额度或套餐本身不够,改代码解决不了。