Skip to main content

简短回答

502 是短暂现象,不需要做任何配置改动:
  1. 根因是服务容器自动重启——重启窗口内网页版打不开、API 也会报 502,两者是同一件事。
  2. 一般 1 分钟内自动恢复——等 30-60 秒重新发起调用即可。
  3. 失败调用不计费——502 期间请求没有真正打进服务,不会产生任何计费记录。
  4. 客户端建议加自动重试——间隔 30 秒左右重试一次,就能无感跨过整个重启窗口。

发生了什么

502 Bad Gateway 的含义是:网关层收到了你的请求,但转发到后端服务时没有得到响应 在 API易 这边,绝大多数瞬时 502 的原因是后端服务容器发生了一次自动重启。重启期间后端进程短暂不可用,于是:
  • 网页版(控制台、充值页等)打不开或报错
  • API 接口api.apiyi.com 等所有节点)返回 502
两者由同一个后端服务支撑,所以会同时出现、同时恢复。系统检测到异常后会自动完成重启,整个过程一般在 1 分钟内结束,无需人工干预。
这类 502 与你的代码、Key、余额、网络配置都无关。如果你是第一次遇到,不需要排查客户端——先等 30-60 秒重试,绝大多数情况下就已经恢复了。

你需要做什么

1

第一步:等 30-60 秒,重新发起请求

容器重启一般在 1 分钟内完成。API 调用直接重发即可;由于失败调用不计费,重试不会产生重复扣费。
2

第二步:网页版打不开时,强制刷新页面

恢复后浏览器可能仍显示缓存的错误页,使用 Ctrl+Shift+R(Windows)或 Cmd+Shift+R(Mac)强制刷新即可看到正常界面。
3

第三步:持续 502 超过 5 分钟,联系客服

瞬时重启不会超过几分钟。如果 502 持续 5 分钟以上,说明不是常规的自动重启,请通过页面底部的联系方式反馈给我们,并附上大致的发生时间(注明时区,如 14:30 (UTC+8))。

给程序化调用加自动重试

如果你的业务对可用性敏感,建议在客户端为 502 这类瞬时错误加上自动重试——间隔 30 秒左右重试一次,即可覆盖整个重启窗口。
重试策略只用于 502/503 这类”没打进服务”的错误。超时断开(客户端 timeout、524)的请求在服务端可能仍在执行并照常计费,盲目重试会造成重复扣费——这类问题请看 如何避免接口超时
如果你的调用频率很高,也可以用指数退避(首次 1 秒、2 秒、4 秒)先快速试探——网络抖动类的瞬时 502 通常几秒内就恢复;仍失败再回落到 30 秒间隔,覆盖容器重启的场景。

常见疑问

不会。502 意味着请求根本没有打进后端服务,没有产生任何模型消耗,因此不会出现在计费记录里这也是一个实用的判断依据:如果某次报错的请求在 调用日志 里查不到计费记录,说明它没有被服务端处理过,放心重发即可。
  • 502:后端服务短暂不可用(容器重启中)。等 30-60 秒重试,不计费。
  • 超时 / 连接中断:客户端 timeout 设置太短,服务端可能仍在执行且照常计费。见 如何避免接口超时
  • 429:并发或速率超限,与服务可用性无关。见 API 可以开多少并发
  • 524:走了 CDN 节点(api-cf.apiyi.com)且请求超过约 100 秒,换节点即可。
处理方向完全不同:只有 502/503 适合直接重试
网页版控制台和 API 接口由同一个后端服务支撑。容器重启时两者会同时不可用、同时恢复——所以「网页也打不开」恰恰说明这是平台侧的瞬时问题,而不是你的客户端配置出了错。
不会常态化。瞬时 502 通常与突发流量高峰有关,属于偶发现象。2026 年 8 月我们已在进行后端服务器扩容升级,此类瞬时 502 的发生频率会显著下降。如遇平台侧异常,我们会第一时间在 实时动态 发布通报和恢复进展。
两个快速判断方法:
  1. 打开网页版:如果 api.apiyi.com 报 502 的同时网页版也打不开,基本可以确定是平台侧瞬时重启,等 1 分钟即可。
  2. 换网络测试:用手机流量(不同运营商)访问网页版或执行下面的命令,能通则说明是你本地网络或代理的问题。
如果换网络后依然全部 502 且持续超过 5 分钟,请联系客服。

相关文档

如何避免接口超时?

timeout 设置、推理模型耗时与 524 排查

使用 API 需要代理网络吗?

国内直连说明与网络环境要求

API易的服务器在哪里?

节点分布、延迟测试与选购建议

服务可用性与 SLA 保障

可用性承诺与故障响应机制

联系我们

企业微信客服

企业微信客服二维码扫码添加,或点击本卡片直接联系客服持续 502 反馈、故障排查

邮件咨询

客服邮箱[email protected]商务合作[email protected]