ChatGPT API 调用超时，不一定意味着 API 密钥失效，也不一定是 VPN 线路速度不够。一次请求可能经过本地应用、代理客户端、DNS 解析、TLS 握手、网络出口和 OpenAI 服务端；任何一段等待过久或连接中断，都可能让程序报超时。网页端能正常对话，也不能证明 API 请求一定正常，因为两者可能使用不同的域名、连接方式、登录状态和网络代理配置。
排查时应先区分“连接没有建立”“请求已发送但迟迟没有响应”“响应开始后流式输出被截断”三种情况，再一次只改一个条件。这样可以判断问题更接近本地网络、代理规则、客户端超时设置、账户权限还是服务端状态。线路可以改善网络路径的连续性，但不能改变 API 的账户资格、地区政策、模型权限或计费状态；服务范围和适用政策应以 OpenAI 官方信息为准。
先判断超时发生在哪个阶段
不要只看程序最终打印的“timeout”。先检查报错文本、HTTP 状态码、请求开始与结束时间，以及是否收到了响应头或部分内容。连接超时通常表示客户端未能在预期时间内建立连接；读取超时可能表示请求已经发出，但等待响应内容超过了客户端设置；流式请求则可能在已经收到部分输出后中断。不同阶段对应不同排查方向，直接换线路可能掩盖原来的问题。
| 现象 | 优先检查 | 下一步处理 |
|---|---|---|
| 连接阶段立即失败 | 代理是否生效、DNS 是否可用、TLS 握手是否完成 | 检查目标域名的分流规则和代理日志，再用已知正常的网络环境对照 |
| 等待一段时间后报读取超时 | 模型响应时间、客户端读取超时设置、出口连接是否稳定 | 确认请求规模和模型配置，合理调整客户端等待策略，并检查是否有中间层主动断开 |
| 收到部分内容后停止 | 流式连接是否被代理、网关或应用缓冲 | 查看流事件与连接日志，分别测试流式和非流式请求 |
| 返回明确的 HTTP 错误 | 状态码、响应体、账户与项目权限 | 按错误类别处理，不要把认证或配额错误当成网络超时 |
例如，401 通常应先核对认证信息；403 要查看响应说明及账户或项目权限；429 需要检查限速或可用额度相关信息。服务端错误或网络中断，则应结合响应体、请求时间和服务状态判断。状态码只是定位线索，具体原因仍以 API 返回内容和官方说明为准。排障记录中可以保存时间、请求模型、状态码、客户端版本和网络模式，但不要记录完整密钥或敏感请求正文。
检查请求、密钥与项目配置
如果网页端正常而 API 失败，先确认两者使用的并不是同一套身份与权限。网页登录状态不会自动为程序提供 API 认证；API 请求通常需要在请求头中使用有效的密钥，并且密钥应属于有权限访问目标项目或模型的账户环境。还要检查程序实际读取的是哪一个环境变量，避免终端、IDE、容器或后台服务各自加载了不同配置。
将密钥放在环境变量或受控的密钥管理设施中，不要写入前端代码、公开仓库、日志、截图、命令历史或可共享的配置文件。排查时可确认密钥是否存在、是否被意外截断，以及请求头是否按 SDK 或官方接口文档要求传递，但不要把真实密钥复制到在线调试工具或聊天窗口。如果密钥曾经暴露，应按官方流程撤销并更换，同时检查相关使用记录。
随后核对请求本身：目标模型名称是否正确、请求格式是否符合当前接口、输入内容是否过大、是否误传了不支持的参数。代码中捕获异常时，要把连接错误、读取超时、HTTP 错误和解析错误分开记录。若只保留一条笼统的“请求失败”，就很难区分网络问题与请求配置问题。更新 SDK 后也应核对迁移说明，避免旧代码与新版本的调用方式混用。
- ✅ 确认运行进程读取了预期的密钥和项目配置。
- ✅ 对照当前官方文档检查模型、请求格式和 SDK 用法。
- ✅ 记录状态码与经过脱敏处理的错误信息，保留必要的排查线索。
- ❌ 不在浏览器前端或公开代码中直接放置 API 密钥。
- ❌ 不因网页端可用，就推断 API 权限、额度和模型权限也正常。
检查 VPN 路由、DNS 与连接连续性
启用 VPN 后，先确认应用实际流量进入了代理，而不是只让浏览器走代理。许多客户端支持系统代理、规则模式或 TUN 模式：系统代理通常只影响主动读取系统代理设置的应用；规则模式会根据域名或进程决定直连和代理；TUN 模式则由虚拟网络接口接管更多流量。具体行为取决于操作系统和客户端，不能仅凭开关显示“已连接”就认定 API 进程已经走代理。
检查目标 API 域名是否命中预期规则，并查看客户端连接日志或系统网络日志。若域名被设为直连，程序可能继续使用本地网络出口；若域名走代理但 DNS 仍从另一条路径解析，也可能出现连接目标不一致或解析失败。不同客户端对远程 DNS、Fake-IP、TUN 和规则集的实现不同，排查时应先恢复到一套简单、明确的配置，再逐项增加自定义规则。
线路选择侧重稳定和连续，而不是只看一次测速结果。API 请求包括握手、等待响应和持续接收数据；短时速率较高但容易断开或频繁切换出口的线路，仍可能让长请求失败。先固定一个可用出口，在相同请求下观察连接是否保持，再更换单个节点做对照。不要在请求进行过程中切换线路，也不要同时启动多个会修改系统路由的代理客户端，否则默认路由、DNS 和系统代理可能互相覆盖。
如果本地网络限制 UDP 或客户端使用了特殊传输方式，可尝试在客户端支持的范围内改用兼容当前网络的连接配置；但不要把协议名称当成问题根因。Shadowsocks、VMess、Trojan、Hysteria2 等协议的配置字段和传输行为不同，客户端支持情况也不同。除非日志指向对应握手或传输错误，否则一次替换多个协议、规则和 DNS 选项，会使结果无法比较。
为什么网页端正常，API 仍可能超时
网页端和 API 虽然都能提供对话能力，但网络请求路径并不相同。网页端通过浏览器加载页面、登录会话及其自身的请求机制；API 则由你的程序或 SDK 发起独立请求，使用不同的认证方式、域名访问路径和超时策略。浏览器可能已经配置系统代理，而命令行进程、容器或服务器进程并没有继承该配置；反过来，程序环境变量中的代理设置也可能让 API 请求经过网页端没有使用的中间代理。
网页端一次对话能返回内容，也不代表 API 调用使用相同模型权限、计费额度或速率限制。API 的账户、项目和计费设置需要单独确认。若网页端可用、API 返回明确的认证或额度错误，应按响应内容处理，而不是不断切换线路。若 API 请求没有收到 HTTP 响应，再进一步检查 DNS、代理覆盖范围、TLS 握手和连接超时。
流式输出还会带来额外差异。应用、反向代理或企业网关如果缓冲响应，可能让客户端长时间看不到增量内容；连接被中间层关闭时，也可能只收到部分事件。可以用受控的小请求分别测试普通响应与流式响应，并检查客户端是否正确读取事件流。若关闭流式后正常、开启后中断，应优先检查流式读取逻辑与中间层行为，而非先认定 API 服务不可用。
调整客户端超时与重试策略
SDK 或 HTTP 客户端通常分别处理连接等待、响应读取和整个请求的最长等待时间。若时间设置过短，网络稍有波动或模型生成较慢就会被提前终止；若无限等待，程序又可能长期占用任务资源。应按应用场景设定合理的连接与读取策略，并查看所用 SDK 当前版本如何解释超时参数。不要直接照抄其他项目的数值，因为请求内容、模型、运行环境和服务端响应时间都会影响等待时长。
重试也要有边界。对于暂时性网络错误或可恢复的服务端错误，可以采用有限重试，并逐步延长重试间隔，避免故障时瞬间重复发送大量请求。对于认证、权限、参数格式或额度错误，重复请求通常不会解决问题，应先修正对应设置。特别是生成类请求，重试前要考虑请求是否已经被服务端处理，避免应用把一次失败的等待误判为“请求完全没有发生”，继而重复产生任务或费用。
应用可以为每次请求生成本地关联标识，并记录开始时间、结束时间、超时类型、尝试次数及响应状态；记录内容需要脱敏。若请求经过自建网关、容器入口或反向代理，还要检查这些中间层的连接保持和读取限制是否短于应用预期。只增加 SDK 超时，并不能让已经被中间层断开的连接恢复。
最后核对计费状态并按顺序复测
网络恢复后仍有问题，应检查 API 控制台中的项目、账单、可用额度、限速信息和模型访问设置。网页端订阅与 API 使用并不应被假定为同一计费渠道；具体权限和费用以账户控制台及官方说明为准。收到配额或限速相关错误时，保存错误响应并检查账户配置；不要通过反复重试来“测试”是否恢复，这可能增加请求量，却不能修复账户状态。
建议按由近及远的顺序复测：先确认程序读取的配置和密钥，再验证请求格式；随后确认系统代理或 VPN 客户端是否接管 API 进程流量，然后查看 DNS、TLS 与连接日志；接着用固定线路比较普通请求和流式请求；最后核对项目权限、账单与服务状态。每轮保持请求内容和运行环境尽量一致，记录实际变化。若问题只在特定网络出现，提供脱敏日志向网络服务提供方咨询；若请求已到达服务端且返回明确错误，则按官方错误说明或支持渠道处理。
复测完成后，移除临时调试日志中的敏感字段，确认密钥仍只保存在受控位置，并恢复不再需要的诊断配置。遇到持续性问题时，准备错误类别、时间范围、客户端与 SDK 版本、网络模式以及脱敏后的请求标识，通常比只提供“API 很慢”更有助于定位。始终以 OpenAI 官方文档、账户页面和服务状态信息为准，不要将线路可连接等同于服务必然可用。
- ✅ 先区分连接超时、读取超时、流式中断和 HTTP 错误。
- ✅ 从实际运行 API 的进程检查代理、DNS、密钥与请求配置。
- ✅ 固定线路并逐项复测，保留脱敏后的时间与错误信息。
- ✅ 单独检查 API 项目权限、计费与限速状态。
- ❌ 不公开密钥，不对认证或额度错误盲目重试。
- ❌ 不把 VPN 当作账户资格或服务政策的替代方案。