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]