疑難排解
錯誤代碼參考
先區分 AIXHUB、相容協定層、上游與客戶端錯誤，再判斷請求是否適合重試。
請先保留原始 HTTP 狀態、回應內容、request ID、Retry-After 與最後一個串流事件，再使用本頁。OpenAI Responses 與 Anthropic Messages 的錯誤封裝可能不同，因此要依可觀察狀態與來源判斷，不能只比對一段 message 文字。
前置條件
先取得 HTTP 狀態、錯誤代碼或最後一個串流事件。若目前只有「請求失敗」而沒有這些資訊，請先依疑難排解重現最小請求。
操作步驟
錯誤代碼表
| 情境 | HTTP / 狀態 | 可能代碼 | 來源 | 含義 | 處理方式 | 何時重試 |
|---|---|---|---|---|---|---|
| API Key 缺少或無效 | 401 | API_KEY_REQUIREDINVALID_API_KEY | AIXHUB | 服務沒有收到有效的 API Key，或金鑰已被撤銷、停用或貼錯。 | 確認使用的是 API Key，不是控制台登入密碼；重新複製完整金鑰並檢查客戶端讀取的變數。 | 修正金鑰或認證設定後再試。 |
| 帳戶、分組或訂閱無權使用 | 403 | ACCESS_DENIEDAPI_KEY_EXPIREDGROUP_NOT_ALLOWED | AIXHUB | 金鑰可能有效，但目前帳戶、金鑰分組、有效期或訂閱不允許這次請求。 | 查看帳戶、API Key、套餐或訂閱狀態；確認模型屬於金鑰可使用的分組。 | 權限或套餐狀態更新後再試；不要原樣大量重送。 |
| 帳戶餘額不足 | 403 | INSUFFICIENT_BALANCE | AIXHUB | 目前可用餘額不足以接受這次請求。餘額不足通常不是 429 速率限制。 | 查看儀表板和用量記錄，完成充值或套餐操作，並確認餘額已更新。 | 餘額更新後再試；重新產生內容前先查看是否已產生用量。 |
| 請求格式或模型參數錯誤 | 400 | invalid_request_error | 相容協定層 | 端點、JSON 結構、必要欄位、模型 ID 或參數與目前協定不一致。 | 回到對應的 API 或客戶端教學，核對 Base URL、請求格式和從可用渠道複製的模型 ID。 | 修正請求後再試，不要重複發送同一個錯誤請求。 |
| 請求內容過大 | 413 或 400 | invalid_request_error | 相容協定層 | 提示、附件、圖片或整個請求超出目前端點能接受的大小。 | 縮短輸入、移除不必要附件或拆分任務，再逐步恢復內容。 | 內容縮小後再試。 |
| 速率、並行數或配額限制 | 429 | rate_limit_errorrate_limit_exceededUSAGE_LIMIT_EXCEEDED | AIXHUB 或上游 | 請求速度、同時執行的任務數或金鑰配額暫時超過限制。 | 降低並行數和請求頻率；如果回應包含 `Retry-After`，按它指定的時間等待。 | 等待後以有限次數重試，不要輪換金鑰規避限制。 |
| 模型目前不可用 | 400、403 或 503 | invalid_request_errorapi_error | AIXHUB 或上游 | 模型 ID 不存在、模型不屬於目前分組，或暫時沒有可處理該模型的可用帳戶。 | 重新查看可用渠道，核對模型 ID、協定、金鑰分組和服務狀態。 | 模型恢復或改用面板當下可用的模型後再試。 |
| 上游或路由暫時失敗 | 502 或 503 | upstream_errorserver_erroroverloaded_error | 上游或路由 | AIXHUB 已收到請求，但上游帳戶、路由或服務容量暫時無法完成。 | 保留 request ID 和發生時間，先確認面板用量，再查看服務狀態或聯絡支援。 | 等待後有限次數重試；持續失敗時不要無限重送。 |
| Responses 串流中途失敗 | HTTP 200，之後為串流事件 | response.failed | 相容協定層 | 連線先回傳 200，但後續 SSE 以 `response.failed` 結束；只檢查初始狀態碼會誤判為成功。 | 持續讀取串流直到完成或失敗事件，將部分輸出視為不完整，並保留事件中的錯誤資訊。 | 確認用量和請求是否已接受後，再建立新的串流。 |
| 客戶端或網路中斷 | 客戶端或網路狀態 | N/A | 客戶端或網路 | 客戶端取消、代理逾時、網路中斷或程序結束，可能讓請求在完成前失去連線。 | 檢查客戶端日誌、代理和逾時設定，再到用量記錄確認請求是否已被接受。 | 先確認沒有重複計費或重複執行，再建立新的請求。 |
來源欄會區分 AIXHUB 可觀察狀態、相容協定層、上游及客戶端／網路失敗。除非明確標示為 AIXHUB 契約，供應商專屬或內部代碼可能隨部署變動，不應視為永久承諾。
如何使用這份參考
- 先保留 HTTP 狀態、request ID、
Retry-After與完整的已遮蔽回應。 - 依實際封裝讀取
code、error.type、error.code與message，再在表格中比對可能代碼。 - 依「來源」區分 AIXHUB、相容協定層、上游或客戶端／網路問題。
- 依「處理方式」修正原因；只有符合下方重試邊界時才重新送出請求。
- 仍無法定位時，回到疑難排解執行最小請求並核對用量記錄。
驗證結果
套用表格中的處理方式後，只重跑一次最小請求，並確認最後狀態或串流終止事件成功，且用量記錄與測試時間及模型一致。
修正後的最小請求只完成一次，最後狀態成功，而且用量記錄與本機測試一致。
常見問題
可搜尋代碼索引
- 認證與存取：
API_KEY_REQUIRED、INVALID_API_KEY、ACCESS_DENIED、API_KEY_EXPIRED、GROUP_NOT_ALLOWED。 - 計費：
INSUFFICIENT_BALANCE是 HTTP 403，不是 429 速率限制。 - 請求格式與模型：
invalid_request_error、api_error。 - 限制：
rate_limit_error、rate_limit_exceeded、USAGE_LIMIT_EXCEEDED。 - 暫時服務失敗：
upstream_error、server_error、overloaded_error。 - Responses 串流失敗：連線以 HTTP 200 開始後，仍可能收到
response.failed。
重試邊界
- 400、401、403 與 413 必須先修正，不可重送相同的無效或未授權請求。
- 429 要遵守
Retry-After、降低並行數，並使用有上限且帶抖動的指數退避。 - 502 或 503 只做有限次數重試。持續失敗時停止，並保留 request ID。
- 只自動重試冪等操作，或已確認服務未接受的生成請求。
- 不可把部分串流輸出與後續重試結果拼接成一份完整輸出。
聯絡支援時，請提供包含時區的失敗時間、request ID、客戶端名稱與版本、端點、協定、模型、HTTP 或事件狀態、已遮蔽回應，以及用量記錄是否出現該請求。不要提供完整 API 金鑰、Cookie、控制台 Token、提示內容或未遮蔽的使用者資料。
下一步
回到疑難排解、查看用量記錄，或重跑認證與 Base URL的最小請求。協定專屬說明請參考 OpenAI Responses與 Anthropic Messages。
官方資料
最後核對：2026-07-14