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 路由設計備援，並以串流指南處理事件與逾時問題。