AI API 錯誤指南:401、403、429 與 5xx

診斷 AI API 的驗證、存取政策、速率限制、用戶端取消與服務商故障,並判斷何時可以安全重試。

AI API 錯誤指南:401、403、429 與 5xx

診斷 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 是容量或政策訊號,而不是要您在密集迴圈中立即重試的指示。請先判斷限制屬於金鑰額度、帳號、模型群組,還是所選路由。

對於可重試的速率限制:

  1. 若有 Retry-After,請遵守它;
  2. 使用加上隨機抖動(jitter)的指數退避;
  3. 限制嘗試次數與總耗時;
  4. 將應用程式的並行數控制在已知的範圍內;
  5. 只有在備援群組能維持所請求的模型與協定時,才依序使用備援群組。

建立更多 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 回應都應該重試嗎?

不應該。只重試可安全重複的操作,設定嘗試次數與時間預算上限,並保留第一次的錯誤。確定性的轉接器或請求問題,不會因為重複執行而改善。