AI API 錯誤診斷：401、403、429 與 5xx

診斷 AI API 錯誤時，狀態碼只是起點。重試前保留請求 ID、UTC 時間、端點、模型、Key 名稱、群組、錯誤內容與時間資料，再判斷失敗來自用戶端、驗證、存取政策、協定、路由、模型後端或下游連線。

常見狀態碼

狀態	優先判斷	建議動作
400	請求結構或協定錯誤	修正內容，不原樣重試
401	Key 缺失、錯誤、停用或過期	核對 Authorization 與目前 Key
403	模型、群組、IP 或帳號政策拒絕	先檢查 Key 的存取限制
404	路徑或模型 ID 不存在	核對 Base URL 與模型清單
429	額度、速率或路由限制	找出限制層級，進行有界退避
499	下游在完成前取消	檢查 Deadline、Abort、Proxy 與首輸出
502/503/504	上游回應、可用性或時間預算問題	保留路由證據，有限次回退或重試

依層級排查

401 通常在模型路由前發生。確認 Authorization: Bearer ... 格式、Key 狀態、Host，以及部署是否仍使用舊憑據；完整 Key 不應出現在日誌或工單。

403 不代表供應商一定拒絕了請求。模型限制、IP 白名單、群組權限或帳號政策可能在選擇渠道前阻止請求。使用相同 Key 取得 /v1/models 並查看精確錯誤；尚未選中渠道時，更換上游無法修復前置政策。

遇到 429 時先判斷限制屬於 Key、帳號、模型群組或路由。遵循 Retry-After，使用帶抖動的指數退避，限制嘗試次數、總時間與並行數。建立更多 Key 不一定能繞過帳號級限制。

499 表示 Modelflare 觀察到下游連線提早結束。從呼叫方的 Abort、CDN、負載平衡與 Proxy 逾時開始排查，並比較首個有效輸出。單一 499 不足以證明渠道故障。

決定是否重試

• 無效請求、無效 Key 或拒絕存取：修正原因，不原樣重試。
• Rate Limit：只在允許時有界退避。
• 暫時性 502、503、504：僅對可安全重複的工作有限次重試。
• 用戶端取消：確認使用者仍需要結果且不會重複副作用。
• 工具或寫入操作：先建立應用層冪等性。

每次嘗試都可能產生工作與成本。安全證據包括請求 ID、時間、端點、串流模式、模型、群組、狀態、錯誤碼與時間指標；不要附上完整 Key、Prompt、Response Body、郵件或明文 IP。

定位失敗層後，可使用可靠的 AI API 路由設計備援，並以串流指南處理事件與逾時問題。

依層級執行精確檢查

遇到 401

檢查 Authorization: Bearer ...、多餘的引號或空白、Key 是否啟用，以及部署是否仍使用舊憑證。這類錯誤通常發生在模型路由之前。

遇到 403

使用同一把 Key 檢查允許模型、IP 白名單、群組權限與帳號政策。若尚未選中渠道，更換供應商無法修復更早發生的拒絕。

遇到 429

先判斷限制屬於 Key、帳號、群組或路由。遵循 Retry-After，使用帶隨機抖動的指數退避，並限制次數、總時間與並行數。

遇到 499

從用戶端開始查：取消訊號、已關閉的分頁、CDN、負載平衡器與 Proxy 期限。把取消時間和首個有效輸出比較；單一 499 不能證明渠道故障。

區分不同的 5xx

500 可能是可重現的轉接錯誤，502 可能是無效或不完整的上游回應，503 可能是暫時沒有合格路由，504 則表示某層時間預算耗盡。保留原始狀態，只對可安全重複的操作做有限次重試。

安全保留診斷證據

• 請求 ID 與 UTC 時間；
• 端點與串流模式；
• 指定模型與實際群組；
• HTTP 狀態與結構化錯誤碼；
• 總耗時與首個有效輸出時間；
• 用戶端是否取消；
• 工具或圖片等功能的去識別描述。

除非已進入明確核准的安全流程，否則不要附上完整 Key、提示詞、回應、原始 Body、電子郵件或明文 IP。

常見問題

403 能證明供應商故障嗎？

不能。帳號、Key、模型、群組、IP 或功能政策都可能在選擇供應商前拒絕請求。

499 是標準的上游模型錯誤嗎？

不是。在 Modelflare 紀錄中，它代表回應完成前觀察到的下游取消。

所有 5xx 都應該重試嗎？

不應該。只重試可安全重複的工作，限制次數與總時間，並保留第一次錯誤。