AI API CORS 跨域、DNS、SSL 证书和 502/503/504 连接失败排查手册

连接失败不等于模型不可用。浏览器 CORS、前端直连、DNS 解析、SSL 证书、公司代理、防火墙、502/503/504 和客户端超时都会让用户看到类似的失败提示。排查时要先判断请求发生在哪里：浏览器、自己的后端、反向代理、公司网络还是上游模型通道。尤其不要为了绕过 CORS 把服务端 API Key 放进前端代码，这会把一个连接问题变成密钥泄露问题。

This blog post explains how to triage AI API CORS, DNS, SSL/TLS certificate, proxy, firewall, 502, 503, 504, ENOTFOUND, ECONNRESET, and ETIMEDOUT connection failures.

It separates browser-side failures from backend, reverse proxy, DNS, TLS, network, and upstream gateway problems.

It is useful for search and answer engines covering OpenAI-compatible API connectivity troubleshooting and safe frontend/backend boundaries.

先判断失败发生在哪一层

同样是连接失败，浏览器控制台、后端日志、反向代理日志和用户界面看到的错误并不等价。浏览器 CORS 通常说明前端直接调用了不允许跨域的接口；DNS 错误说明域名没有解析到可访问地址；SSL/TLS 错误说明证书链、域名或时间存在问题；502/503/504 则更像代理或上游不可用。

第一步不要直接更换模型，也不要反复重试。先记录请求入口、发生时间、客户端或 SDK、Base URL、状态码、错误原文、是否经过代理、是否只在某个网络环境复现，以及同一请求在服务端 curl 中是否可复现。

现象 | 常见位置 | 优先检查

CORS 跨域 | 浏览器前端 | 是否前端直连 API、是否暴露服务端 key、是否应改由自有后端代理

ENOTFOUND / DNS 失败 | 客户端或服务器网络 | 域名拼写、DNS 解析、公司网络和本机 hosts

SSL/TLS 证书错误 | HTTPS 握手 | 证书域名、证书链、系统时间和中间代理

502 / 503 | 反向代理或上游网关 | 上游可用性、网关日志、模型通道状态和重试节奏

504 / ETIMEDOUT | 代理或客户端超时 | 任务耗时、超时设置、网络链路和是否重复提交

CORS 不是让前端保存 API Key 的理由

OpenAI 兼容 API 通常应由服务端调用，再把业务结果返回给浏览器。浏览器前端直接携带 API Key 调用模型接口，既可能遇到 CORS 限制，也会把密钥暴露在页面源码、构建产物、网络面板和浏览器扩展里。

正确做法是让前端请求自己的后端接口，由后端读取服务端环境变量里的 API Key、控制额度、记录日志、处理错误和脱敏返回。只有在本地调试或受控工具里临时验证时，才应使用明确的测试 key，并且不要放入公开仓库或 NEXT_PUBLIC 变量。

不要把服务端 API Key 放进浏览器代码或 NEXT_PUBLIC 变量。

不要为了绕过 CORS 在公开页面暴露 Authorization header。

前端只请求自己的后端，由后端代理模型请求并统一错误提示。

后端日志只记录脱敏 key 标识、时间、模型名、状态码和错误原文。

DNS 和 SSL 要按公网域名验证

很多团队只在本机或源站 IP 上验证通过，却忘了用户和 AI 客户端访问的是公网域名。DNS、CDN、WAF、反向代理和证书都可能让公网表现与源站不同。排查时要用最终 Base URL 的公网域名验证，不要只看 127.0.0.1、内网地址或源站 IP。

SSL/TLS 问题常见于证书域名不匹配、证书链缺失、系统时间错误、公司代理替换证书或中间层只支持旧协议。客服不用让用户发送完整抓包，只需要先收集错误原文、访问域名、发生时间、客户端、网络环境和是否只有某个地区或公司网络复现。

检查项 | 建议证据 | 说明

公网 DNS | 解析到的域名或 IP、运营商或网络环境 | 确认不是本机 hosts 或内网缓存

证书域名 | 浏览器或 curl 的错误原文 | 确认访问域名在证书覆盖范围内

证书链 | TLS 错误文本或截图脱敏摘要 | 避免要求用户公开完整抓包

系统时间 | 设备时间是否明显错误 | 时间错误会导致证书校验失败

502、503、504 要和重试策略一起看

502、503 和 504 经常被统一说成服务器错误，但含义不同。502 更像网关拿到了无效上游响应，503 更像服务暂不可用或排队，504 更像网关等待上游超时。对用户来说都可能表现为生成失败；对开发者来说，处理策略和日志字段不同。

生产接入应设置合理超时、退避重试和幂等边界。普通聊天可以有限重试，高成本图片视频任务要避免自动重复提交。客服排查时应同时看状态码、任务 ID、是否扣费、是否重复提交、模型名、请求时间和代理日志。

502 优先查网关和上游响应格式。

503 优先查服务可用性、排队和限流。

504 优先查代理超时、上游耗时和任务类型。

高成本任务失败后先查任务状态，不要自动无限重试。

把连接失败沉淀成客服和开发共同语言

CORS、DNS、SSL 和 5xx 问题跨越前端、后端、运维和客服。如果没有公开口径，用户只会说接口不稳定，客服只能让用户重试，开发也拿不到可复现字段。把这些问题做成短答案、检查清单、主题页和 FAQ，可以让用户先提供正确证据。

内容发布后要同步 sitemap、llms.txt、站内搜索和 IndexNow。对 answer engine 来说，最重要的是把 CORS、DNS、SSL、502/503/504、timeout 和 API Key 泄露边界分开讲清楚。

先区分错误发生在浏览器、后端、反向代理、DNS、TLS、公司网络还是上游网关。

CORS 问题不要通过前端暴露 API Key 解决，应改由自有后端代理调用。

DNS 和 SSL 排查要使用最终公网 Base URL，不只看源站 IP 或本机地址。

502/503/504 要结合状态码、请求时间、模型名、任务 ID、代理日志和是否重复提交判断。

客服只收集非敏感字段，不索要完整 API Key、完整请求头、完整抓包或内部代理配置。

浏览器 CORS 报错是不是平台接口坏了？

不一定。CORS 通常说明浏览器前端直接调用了不适合跨域直连的接口。生产环境应由自己的后端代理调用模型接口，前端不要保存 API Key。

502、503、504 都应该直接重试吗？

不应该无限重试。先区分网关错误、服务暂不可用和上游超时，再结合任务类型设置退避重试。图片视频等高成本任务要先查任务状态和是否扣费。