AI API 錯誤指南:401、403、429 與 5xx
診斷 AI API 的驗證、存取政策、速率限制、用戶端取消與服務商故障,並判斷何時可以安全重試。

診斷 AI API 錯誤時,把狀態碼當成調查的起點、而不是完整的原因,問題最容易釐清。重試之前,請先保留請求 ID、時間戳記、端點、模型、API 金鑰名稱、所選群組、回應本文與時間資料。
目標是找出究竟是哪一層拒絕或結束了請求:用戶端、驗證、存取政策、協定驗證、路由、模型後端,或下游連線。
常見狀態碼通常代表什麼
| 狀態 | 初步判讀 | 第一步行動 |
|---|---|---|
| 400 | 請求結構、欄位或協定契約無效 | 將請求內容與所選端點比對;不要原封不動重試 |
| 401 | 憑證缺少、格式錯誤、已停用、已過期或無效 | 檢查 Authorization 標頭與目前使用的金鑰 |
| 403 | 已通過驗證,但遭帳號、模型、群組、IP 或政策阻擋 | 測試管道之前,先檢查金鑰限制與模型/群組存取權 |
| 404 | 端點路徑錯誤,或模型識別碼無法使用 | 確認 Base URL、路徑與經驗證的模型清單 |
| 429 | 達到請求速率、額度或符合條件路由的限制 | 檢查額度與群組限制;使用有上限的退避或已設定的備援 |
| 499 | 下游用戶端在完成前中斷連線或取消請求 | 檢查用戶端截止時間、中止操作、代理與首次輸出時間 |
| 500 | 內部處理或轉接器(adapter)失敗 | 保留請求 ID;只有在操作可安全重複時才重試 |
| 502/503 | 服務商回應異常、路由無法使用,或暫時性容量問題 | 檢查路由證據,並使用有上限的備援或重試 |
| 504 | 閘道或服務商的時間預算已用盡 | 將首次輸出與總時間和用戶端截止時間比較 |
這些判讀只是診斷的起點。特定呼叫的實際原因,取決於錯誤本文與請求記錄。
更換模型前先診斷 401
401 通常發生在任何有意義的模型路由之前。請檢查:
- 標頭是否使用 Authorization: Bearer ...;
- 應用程式是否誤把引號、空白字元或預留位置值一起送出;
- 金鑰是否已啟用且尚未過期;
- 請求是否送到預定的 Modelflare 主機;
- 機密管理服務或部署環境是否仍保留輪替前的舊金鑰。
請勿把完整金鑰貼到日誌或客服訊息中。如果可能已經外洩,請用專用的測試金鑰重現問題,然後撤銷外洩的憑證。
先把 403 當成存取政策問題診斷
403 並不一定代表服務商拒絕了請求。驗證可能成功,但在選擇管道之前,存取就因下列原因失敗:
- 金鑰限制了所請求的模型;
- 金鑰的 IP 允許清單不包含觀察到的用戶端 IP;
- 帳號無法使用所選的模型群組;
- 使用者或金鑰因政策而被停用;
- 該路由不允許所請求的功能。
請用同一把金鑰取得 /v1/models,檢查它的群組與模型限制,並比對確切的錯誤代碼。如果根本還沒選定管道,更換服務商管道也無法改變先前的政策判定。
診斷 429 時避免造成重試風暴
429 是容量或政策訊號,而不是要您在密集迴圈中立即重試的指示。請先判斷限制屬於金鑰額度、帳號、模型群組,還是所選路由。
對於可重試的速率限制:
- 若有 Retry-After,請遵守它;
- 使用加上隨機抖動(jitter)的指數退避;
- 限制嘗試次數與總耗時;
- 將應用程式的並行數控制在已知的範圍內;
- 只有在備援群組能維持所請求的模型與協定時,才依序使用備援群組。
建立更多 API 金鑰,並不一定能繞過帳號層級或群組層級的請求限制。
從呼叫端往外診斷 499
當下游用戶端連線在回應完成前結束時,Modelflare 可能會記錄 499。請從呼叫端開始檢查:
- 是否觸發了中止(abort)訊號?
- 用戶端、負載平衡器、CDN 或反向代理是否達到閒置或總逾時?
- 使用者是否關閉了頁面或停止了 Agent?
- 串流是否只產生了工具事件,沒有可見文字?
- 首個有效輸出出現前經過了多久?
單一筆 499 記錄並不能證明管道中斷。變更路由政策之前,請先比較同一時段內、相同模型/群組的其他請求。
依層級區分 5xx 失敗
遇到 5xx 時,請保留原始狀態與錯誤詳情,不要在用戶端把所有失敗都轉成籠統的 500。
- 驗證或轉接器造成的 500 可能是確定性的,原封不動重送很可能再次失敗。
- 502 可能表示服務商的回應無效或不完整。
- 503 可能表示沒有符合條件的路由,或暫時無法使用。
- 504 表示時間預算已用盡,但仍需找出是哪一層造成的。
請利用請求時間、所選群組、客服團隊可取得的管道證據,以及鄰近時段的請求,區分是單次異常回應還是持續性的路由問題。
決定是否重試
| 失敗類別 | 預設的重試決策 |
|---|---|
| 請求內容無效或協定不支援 | 修正請求;不要原封不動重試 |
| 金鑰無效或存取遭拒 | 修正憑證或政策;不要原封不動重試 |
| 額度用盡 | 有計畫地調高額度或重新分派額度;不要反覆重試 |
| 速率限制 | 在允許的情況下,以有上限的退避重試 |
| 暫時性的 502/503/504 | 對冪等的工作重試,並嚴格限制嘗試次數 |
| 用戶端取消 | 只有在使用者仍需要結果、且重複執行是安全的情況下才重試 |
| 工具或寫入副作用 | 重複執行前,必須先在應用程式層確保冪等性 |
重試會產生新的工作,也可能產生新的費用。請記錄每一次嘗試,並避免讓後來的成功掩蓋了原本的失敗。
安全地保留證據
為了客服支援或事件檢討,請記錄:
- 請求 ID 與 UTC 時間戳記;
- 端點與串流模式;
- 所請求的模型與所選群組;
- HTTP 狀態與結構化錯誤代碼;
- 總時間與首個有效輸出時間;
- 呼叫端是否取消;
- 經過去識別化的請求功能描述,例如工具或圖片輸入。
除非經核准的安全流程明確要求,否則請勿附上完整的 API 金鑰、提示詞、回應內容、原始請求本文、電子郵件或明文 IP 位址。
找出失敗的層級後,備援設計請參閱可靠的 AI API 路由,事件與逾時相關的失敗則請參閱串流指南。
常見問題
403 能證明供應商停擺了嗎?
不能。在選定服務商路由之前,帳號、金鑰、模型、群組、IP 或功能政策都可能產生 403。請先檢查請求記錄與錯誤代碼。
499 是標準的服務商模型錯誤嗎?
不是。在 Modelflare 的請求記錄中,它代表在完成前觀察到的下游取消。將它視為模型故障之前,請先調查呼叫端與代理的截止時間。
所有 5xx 回應都應該重試嗎?
不應該。只重試可安全重複的操作,設定嘗試次數與時間預算上限,並保留第一次的錯誤。確定性的轉接器或請求問題,不會因為重複執行而改善。