AIMLAPI 遇到 429 時,先檢查應用程式與 SDK 是否都在重試

AIMLAPI 的官方 Python SDK 文件列出預設自動重試兩次。外層任務若再次重試,請求次數就會疊加;上線前應統一重試責任,並分開處理參數錯誤、餘額不足與流量限制。

來源: github.com
November 11, 2026
1 min

將多個模型接到同一個介面,可以減少串接程式碼,卻不會讓它們具有相同的參數限制或故障行為。對準備將 AIMLAPI 整合到客戶功能的團隊來說,值得先檢查的是系統失敗時會怎麼做:一次使用者操作究竟發出多少次呼叫、多久停止,以及由誰接手處理失敗。本文依據官方錯誤說明、金鑰文件與 Python SDK README 分析這些界線,沒有執行壓力測試。

兩層重試,會放大一次失敗

官方 Python SDK README 表示,連線錯誤、408、409、429 及狀態碼 500 以上的錯誤,預設會自動重試兩次,並可透過 max_retries 調整或關閉。這裡的「兩次重試」是在首次呼叫之外。假設應用程式外層也在失敗後完整重試兩次,而且每次 SDK 呼叫都遇到可重試錯誤,並用完預設重試次數,一次業務任務最多就會產生 3 × 3 = 9 次嘗試。這是根據明確假設計算的上限範例,不是平台實測流量,也不表示九次都會收費。

說明中心將 429 解釋為速率或並行數限制,並建議降低請求速率、退避重試或排入佇列。如果外層只要看到失敗就立即重送,可能持續加重同一項限制。建議由單一層級統一管理重試預算,記錄每次嘗試的原因與次數,再為業務任務設定明確的停止條件。不要讓瀏覽器、任務佇列與 SDK 各自獨立決定無限重送。

等待時間也要另外檢視:SDK README 列出的預設請求逾時為 10 分鐘,可透過 timeout 設定。這個預設值不能直接當成對客戶承諾的等待時間。互動功能需要自己的總等待時間預算與清楚的逾時回應;背景任務則應讓使用者查到處理中、失敗或完成的真實狀態。

有些錯誤,重試無法解決

官方錯誤表列出一種 400 情況:所選模型不支援 messages 中的 system 角色。遇到這種情況,應依該模型的 schema 修改請求,而不是假設統一介面就代表所有模型都接受同一組參數。切換備援模型前,也要驗證它能接受現有訊息結構與任務要求,否則一次服務降級會變成另一種請求錯誤。

錯誤表也將餘額或方案額度用盡列為 403。它與 429 的處理方向不同:前者需要檢查帳戶額度與預算,後者需要控制呼叫節奏。建議在監控中分別分類,並保留不含敏感內容的請求識別碼與錯誤資訊。不要把所有非成功回應都歸為「模型忙碌」,也不要用自動儲值取代故障診斷。

控制支出,不能取代控制流量

金鑰文件允許為每個 API key 設定消費上限,達到後會阻止該 key 繼續產生費用;可選擇每日、每週、每月等重設週期,依 UTC 時間重設。文件也允許限制 key 可以呼叫的端點。這些設定有助於區隔專案用途與支出界線,但消費上限不是呼叫速率設定,也不能證明不會發生重複嘗試。

整合前,可以請團隊用一個受控失敗情境核對記錄:是否區分 400、403 與 429、實際嘗試次數是否符合預算、總等待時間是否符合產品要求,以及備援模型是否經過相容性檢查。如果這些問題仍無人負責,統一介面帶來的便利還不足以支持上線承諾。先完成這一輪驗收,再擴大呼叫量。

內容說明:本文基於公開資料整理,僅供工具選型參考。產品功能、價格及相關政策可能隨時調整,請以官方最新資訊為準。

原文出處:github.com