本篇要点
- 四层:解析 → 握手 → HTTP 状态 → 业务限流,逐层排除。
- 不带 Key 先测连通,能立刻分清「网络不通」与「身份不对」。
- 401 是身份,403 是地区或权限,429 是频率或额度。
四层定位
| 层 | 怎么测 | 正常表现 | 异常含义 |
|---|---|---|---|
| 域名解析 | dig 或 nslookup 目标域名 | 返回 A / AAAA 记录 | 无记录:域名写错或被拦 |
| TLS 握手 | curl -I https://端点 | 返回 HTTP 响应头 | 卡住或重置:SNI 被拦、出口被限 |
| HTTP 状态 | 看返回码 | 2xx 或 401 | 403 地区或权限,5xx 服务端 |
| 业务限流 | 看 retry-after 与额度页 | 无 429 | 429:并发过高或额度用尽 |
顺序不能反。先查状态码的人,会把 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 说明额度或套餐本身不够,改代码解决不了。