錯誤與重試
只重試暫時性故障;請求錯誤應先修正再傳送。
呼叫失敗時,先保存 HTTP 狀態、遮罩敏感資訊後的錯誤內容、呼叫時間、端點、Model ID 和可用的請求識別碼,再決定是否重試。
常見錯誤
| 表現 | 優先檢查 | 是否直接重試 |
|---|---|---|
400 參數錯誤 | JSON、Model ID、欄位類型和模型支援 | 否,先修正請求 |
401 身分驗證失敗 | API Key、Bearer 格式和憑證狀態 | 否,先修正憑證 |
403 存取受限 | 帳號、模型範圍、地區或來源限制 | 否,先確認權限 |
404 路徑或資源不存在 | API 位址、端點、Model ID 或任務識別碼 | 否,先核對設定 |
429 請求過多 | 請求頻率、並行和回傳的速率限制提示 | 降低速率後有限次重試 |
5xx 服務異常 | Request ID 和原請求是否已執行 | 根據錯誤有限次重試 |
| 逾時或連線中斷 | 網路、用戶端逾時和請求狀態 | 不要盲目重新傳送 |
| 餘額或預算不足 | 可用餘額、Key 預算和費用保護 | 先解決限制 |
實際錯誤內容和狀態碼以 API 回傳為準。
設定重試
只重試可能恢復的錯誤,並設定最大次數和總等待時間。優先使用回應中明確提供的重試提示。
範例:最多重試 3 次,等待約 1 秒、2 秒、4 秒,並增加少量隨機延遲。這是應用程式端的策略範例,不表示平台限制一定會在對應時間解除。不要同時在 SDK、業務程式碼和閘道開啟無上限重試。
避免重複請求
用戶端逾時後,先到 Requests 檢查原請求狀態。生成圖片或執行耗時較長的任務時,如果已經取得請求或任務識別碼,應先查詢現有狀態。只有介面明確支援冪等機制時,才使用對應欄位或請求標頭。
聯絡客服
提供 Request ID、呼叫時間與時區、Model ID、端點、HTTP 狀態、遮罩敏感資訊後的錯誤以及已經執行的疑難排解步驟。不要傳送密碼、驗證碼、完整 API Key 或無關的敏感內容。