HopBase 文檔錯誤碼與重試
HopBase 的錯誤回應結構、各狀態碼的含義與能否重試、串流請求出錯的表現，以及回報問題時需要提供的資訊。
依現象快速定位請用錯誤速查，本頁是完整口徑。並行上限、逾時與計費規則見並行、逾時與計費。
錯誤回應結構
OpenAI 協定（/v1/chat/completions、/v1/responses、/v1/images/*、/v1/video/*）：
{ "error": { "message": "…", "type": "invalid_request_error", "code": "insufficient_quota" } }Anthropic 協定（/v1/messages）：
{ "type": "error", "error": { "type": "invalid_request_error", "message": "…" } }文案語言依請求標頭 Accept-Language 回傳，未指定時為英文。程式裡請依 HTTP 狀態碼與 code 判斷，不要比對文案。
狀態碼
| 狀態碼 | 常見原因 | 能否重試 | 怎麼做 |
|---|---|---|---|
| 401 | 沒帶金鑰、金鑰不完整、已停用或過期 | 否 | 回主控台「API 金鑰」重新複製或新建 |
| 402 | 帳戶餘額用完；這把金鑰的額度用完；影片提交時餘額不足以涵蓋在途預留 | 儲值後可 | 儲值或調整金鑰額度；不要循環重試 |
| 403 | 方案限制了用戶端，或該能力未開通 | 否 | 換成該方案適用的用戶端或方案 |
| 404 | 模型不在這把金鑰的方案裡、路徑不屬於該方案、方案已下架 | 否 | 用該金鑰呼叫 GET /v1/models 核對 ID；路徑見Base URL 與協定 |
| 413 | 請求內容超過 60 MB | 否 | 壓縮素材，或在模型支援時改傳 URL |
| 429 | 帳戶或金鑰並行已達上限；或該模型目前受限流 | 是 | 依 Retry-After 稍後重試並降低並行 |
| 499 | 用戶端在完成前斷線（手動中斷或讀取逾時先到） | 是 | 長輸出改用串流，並調大用戶端讀取逾時 |
| 502 / 503 | 該模型暫時無法使用，系統已自動換帳號重試仍未成功 | 是 | 退避後重試，或換同系列的其他模型 |
| 504 | 上游處理逾時 | 是 | 退避後重試；長任務改用串流或非同步介面 |
有一類 404 其實是「暫時無法使用」
收到 Model "X" is not supported by any configured account in this group 時，先用這把金鑰呼叫 GET /v1/models：清單裡有這個模型，代表只是暫時無法使用，依 502 / 503 處理；清單裡沒有，才是方案不含該模型。
重試規則
- 不要原樣重試：400、402、403、404、413、422。這些要先改請求、設定或餘額。
- 退避後重試：429、502、503、504，以及串流輸出中斷。建議間隔 2 秒、5 秒、15 秒，最多 3 次。
- 429 會帶重試提示標頭：
Retry-After（秒）與Retry-After-Ms（毫秒），有就依它等待。 - 非同步任務提交成功後不要重複提交：影片與非同步生圖提交成功即已建立任務，重複提交會產生多個任務並各自計費，改為輪詢任務狀態。
串流請求出錯
串流請求一旦開始輸出，HTTP 狀態碼就已經是 200，之後的錯誤透過事件下發，不會再改狀態碼：
- OpenAI 協定：
event: error，Responses 協定為response.failed。 - Anthropic 協定：
event: error。
用戶端要在讀取串流的迴圈裡處理錯誤事件。已收到的片段無法續傳，需要整條請求重新發起。
回報問題時請提供
- 回應標頭
x-request-id（每條回應都有，是定位該請求的唯一識別） - 出現時間（含時區）與模型 ID
- 完整的錯誤原文與 HTTP 狀態碼
帶上這些資訊聯絡我們，可以直接定位到那一條請求。