openai.APIConnectionError: Connection error 的第一含义不是 key 错、额度没了、模型不可用，也不是提示词写错。它表示 SDK 没有完成到当前 endpoint 的连接路径。如果日志里没有 HTTP 状态码、没有 JSON 错误体、没有 request ID，就先把它当作连接路径问题处理。
如果已经返回状态码，归属会改变。401 是认证分支，429 是额度或速率分支，500/503 是服务端或临时可用性分支。本文处理的是最容易被误判的无响应分支：请求还没有带回足够的 API 证据。2026 年 5 月 6 日本次检查时，OpenAI Status 显示服务正常；OpenAI 官方错误码文档把 APIConnectionError 描述为连接服务的问题，并要求检查网络、代理、SSL 证书、防火墙和容器权限。
快速判断
| 你看到的证据 | 优先归属 | 下一步 |
|---|---|---|
| 没有状态码、正文、request ID | 连接路径 | 从同一运行环境测状态页、DNS、TLS、代理、防火墙和出网。 |
| 返回 401 或认证正文 | 认证归属 | 查 key、项目、组织和 endpoint 类型。 |
| 返回 429、insufficient_quota 或 rate header | 额度或速率归属 | 转到额度或速率限制页面，不要继续按连接错误排查。 |
| 返回 500/503 且有 request ID | API/server 分支 | 保留 request ID，有限重试并看状态页。 |
| Azure 或网关路径 | 路由提供方 | 查 base URL、deployment、服务商状态和 outbound HTTPS。 |
先读响应证据
APIConnectionError 最大的价值是告诉你：SDK 可能没有拿到可分类的服务器响应。当前 Python SDK 文档把连接失败映射到 APIConnectionError，把已经返回的 4xx/5xx 响应映射到 APIStatusError 及其子类。因此，没有状态码本身就是证据。
先看日志里的最后一层原因。remote disconnect、DNS failure、TLS certificate error、proxy error、timeout、connection refused 都属于连接路径线索。如果你看到 429 和 insufficient_quota，就转到 OpenAI API quota exceeded。如果看到 RPM、TPM、remaining 或 reset header，就转到 OpenAI API rate limits。不要把这些分支混在一个重试建议里。
这个顺序能保护现场。盲目加重试会让错误暂时变少，但也会把代理、证书、容器出网或 endpoint 写错的问题藏起来。换 key 会引入第二个变量。切到另一个网关只能证明另一条路可能可用，不能解释原路为什么失败。生产事故里，先证明失败路径。
10 分钟同路径测试
测试必须发生在报错的同一台机器、容器、serverless 函数、worker、区域和 base URL 上。本机能通，只能说明本机能通。
- 打开 https://status.openai.com/ 并记录时间。状态页正常不能排除本地路径问题，但可以避免无证据地说 OpenAI 宕机。
- 检查实际调用的 host 是否能 DNS 解析，例如 api.openai.com、Azure 资源域名或网关域名。
- 从同一 runtime 验证 443 TLS。企业代理、自定义 CA、精简容器镜像和受限 egress 最常在这里暴露。
- 核对 base URL 和 endpoint 家族。直连 OpenAI、Azure OpenAI、OpenAI-compatible gateway 不是同一路径。
- 检查 proxy、VPN、firewall、WAF、NAT 是否改写或拦截请求。
- 只有在 key、model、endpoint 和环境变量一致后，才比较本地与线上结果。
不要只记录成功或失败。记录证据第一次变化的位置：DNS 不通、TLS 证书失败、代理拒绝、远端断开、请求超时，对应的修复动作完全不同。
SDK 控制不要遮住证据
Python 里应分别捕获 APIConnectionError、APITimeoutError 和 APIStatusError。把它们全包成一个异常，会丢掉最重要的归属分裂。诊断时设置合理 timeout，临时降低 max_retries，用 OPENAI_LOG=debug 捕获底层原因，但不要长期保留敏感日志。
Node 侧同样要控制 maxRetries、timeout、request ID、raw response 和 proxy fetch。目标不是把失败重试掉，而是保留足够证据判断它是路径失败、超时、已返回状态码，还是代理配置问题。
如果 LangChain、agent 框架、队列或内部网关隐藏了 SDK 层，就用同一 key scope、同一 base URL 和同一 model route 跑一个最小请求。这个动作不是替换业务代码，而是先证明底层路径能不能抵达端点。
路由分支会改变修复动作
直连 OpenAI 时，先证明到 api.openai.com 的路径，再根据返回状态切到认证、额度、速率或服务端分支。Azure OpenAI 需要额外核对 resource endpoint、deployment name、API version、region routing、认证方式和 Azure 网络规则。OpenAI-compatible gateway 要先当作服务商路径处理，除非直连 OpenAI 复现同一症状。
浏览器端调用是另一类问题。CORS、暴露 key、浏览器网络策略和代理设计都可能成为 owner。生产 API 调用应优先移到服务端，再按 SDK 后端路径排查。
Serverless 和容器尤其要小心。构建阶段能安装依赖，不代表运行时能出网。真正有价值的验证，是在正在运行的函数、job 或容器内部发出最小请求。
升级前证据包
升级给支持、云厂商或网关服务商前，准备一个证据包：时间戳和时区、endpoint/base URL、SDK 和版本、model、runtime 和 region、直连 OpenAI 还是 Azure/网关、底层异常、是否存在 status/body/request ID、脱敏日志。不要放 API key、完整敏感 header 或客户数据。
好的证据包会写清已经在同路径证明了什么。例如：2026-05-06 22:40 CST 检查 status 正常；容器内 DNS 正常；TLS 在企业 CA bundle 处失败；没有 request ID 返回。这比一组截图更容易让接手者定位 owner。
FAQ
APIConnectionError 是否说明 OpenAI 宕机？
不说明。它只说明你的请求没有完成连接路径。OpenAI 可能正常，而你的 DNS、TLS、代理、防火墙、容器出网、endpoint 或网关路径失败。
为什么没有 request ID？
通常因为请求没有到达能返回 API 响应的位置。已返回的 API 错误更可能有 request evidence；连接路径失败经常没有。
要不要先换 API key？
不要。换 key 解决的是认证 owner，不解决到不了端点的路径。返回 401 再查认证；没有响应就先查路由。
这是不是 rate limit？
通常不是。rate limit 会返回 429 或速率相关 header。看到这些证据时再进入速率限制页面。
怎样证明修好了？
同一 runtime、同一 base URL、同一 key scope、同一 model route、同一网络路径下，一个最小请求可以稳定成功，并且没有被队列或 wrapper 隐藏结果。