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": "…" }
}Anthropic 結構沒有 code。金鑰校驗階段的錯誤（401、額度 402、帳戶 403）在 /v1/messages 也是 OpenAI 結構。文案語言依請求標頭 Accept-Language 回傳，未指定時為英文。程式裡請依 HTTP 狀態碼與 code 判斷，不要比對文案。
狀態碼
| 狀態碼 | 常見原因 | 能否重試 | 怎麼做 |
|---|---|---|---|
| 401 | 沒帶金鑰、金鑰不完整、已停用或過期 | 否 | 回主控台「API 金鑰」重新複製或新建 |
| 402 | 餘額、金鑰、成員或部門額度用完；影片提交時餘額不足以涵蓋在途預留 | 儲值後可 | 先用 GET /v1/usage 查這把金鑰還能花多少，再儲值或調整額度；不要循環重試 |
| 403 | 帳戶或成員被停用、無權使用或未綁定分組，或能力未開通 | 否 | 聯絡管理員，或換用支援該呼叫的分組金鑰 |
| 404 | 模型不在這把金鑰的分組裡、路徑不屬於該分組、分組已下線 | 否 | 用該金鑰呼叫 GET /v1/models 核對 ID；路徑見Base URL 與協定；已下架的 ID 及替代型號見模型更新日誌 |
| 413 | 請求內容超過 60 MB | 否 | 壓縮素材，或在模型支援時改傳 URL |
| 429 | 帳戶或金鑰並行已達上限；或服務目前繁忙 | 是 | 依 Retry-After 稍後重試並降低並行 |
| 499 | 只見於主控台使用記錄：用戶端先斷線，收不到它 | — | 長輸出改用串流，並調大用戶端讀取逾時 |
| 502 / 503 | 服務暫時無法使用，系統自動重試仍未成功 | 是 | 退避後重試，或換同系列的其他模型 |
| 504 | 處理逾時 | 是 | 退避後重試；長任務改用串流或非同步介面 |
錯誤碼清單
# OpenAI 結構裡的 code。模型自身回的 400 可能帶該模型自己的 code。
狀態 code 含義 能否重試
401 missing_api_key 沒帶金鑰 否
invalid_api_key 金鑰無效或已刪除 否
api_key_expired 金鑰已過期 否
402 insufficient_quota 餘額 / 金鑰 / 成員 / 部門額度用完 儲值後
insufficient_balance 影片：餘額不足以涵蓋在途預留 + 本條預估 任務結束或儲值後
403 account_disabled 帳戶已停用 否
member_disabled 成員帳號已停用 否
member_group_forbidden 成員無權使用這把金鑰的分組 否
api_key_misconfigured 金鑰未綁定分組 否
image_generation_disabled 分組未開通生圖 否
middleware_denied 被網關策略拒絕 否
404 model_not_found 分組不支援該模型 否
model_not_served 分組未提供該模型 否
group_offline 分組已下線 否
route_not_found 該金鑰不支援此路徑 否
400 invalid_request 請求體無法讀取或非 JSON 物件、缺 model、messages 為空 否
413 request_too_large 請求體超過 60 MB 否
429 user_concurrency_limit 帳戶並行上限（Retry-After: 1） 是
apikey_concurrency_limit 金鑰並行上限（Retry-After: 1） 是
all_routes_rate_limited 服務繁忙 是
upstream_rate_limit 服務繁忙 是
502 upstream_error 服務暫時無法使用 是
503 no_available_route 服務繁忙 是
no_available_account 服務繁忙（會話續接例外見下） 是*
all_routes_failed 服務暫時無法使用 是
plugin_unavailable 服務暫時無法使用 是
service_unavailable 認證服務暫時無法使用 是
504 upstream_timeout 逾時 是重試規則
- 不要原樣重試：400、402、403、404、413、422。這些要先改請求、設定或餘額。404 是確定結果：暫時無法使用只回 429 / 5xx，不會回 404。
- 退避後重試：429、502、503、504，以及串流輸出中斷。建議間隔 2 秒、5 秒、15 秒，最多 3 次。例外：提示有狀態會話「can no longer be resumed」的 503，要去掉
previous_response_id開新對話。 - 429 會帶重試提示標頭：
Retry-After（秒）與Retry-After-Ms（毫秒），有就依它等待。 - 非同步任務提交成功後不要重複提交：每次重提都是另一個各自計費的任務，請改為輪詢。
串流請求出錯
串流請求一旦開始輸出，HTTP 狀態碼就已經是 200，之後的錯誤透過事件下發，不會再改狀態碼：
Chat Completions data: {"error": {…}} （不帶 event: 行）
Responses event: response.failed （response.error.code：rate_limit_exceeded / server_error / invalid_prompt）
Anthropic event: error用戶端要在讀取串流的迴圈裡處理錯誤事件。已收到的片段無法續傳，需要整條請求重新發起。
非同步任務失敗
提交被拒直接回一般 4xx，不建任務。受理後失敗時輪詢仍回 200，status: "failed"，原因在 error.message（生圖任務為 error 字串），沒有 code（可靈與 Midjourney 任務例外，會回傳穩定的 error.code，如 input_sensitive、invalid_request、generation_failed），不計費。審核類、參數類失敗不要原樣重提。主控台「使用記錄」顯示分類與建議：
審核 input_sensitive、safety_rejected … 改提示詞或素材
參數 prompt_required、upstream_invalid_request、reference_* … 改參數
逾時 各系列時限見「並行、逾時與計費」 重新提交
中斷 task_interrupted 重新提交回報問題時請提供
- 回應標頭
x-request-id（每條回應都有，是定位該請求的唯一識別） - 出現時間（含時區）與模型 ID
- 完整的錯誤原文與 HTTP 狀態碼
服務端故障在主控台不顯示原文，排查以 x-request-id 為準。帶上這些資訊聯絡我們，可以直接定位到那一條請求。