跳到正文
HopBase 文檔
登入控制台

報錯速查

按錯誤訊息快速排查協議、金鑰、模型和環境問題。

按類別找到對應的現象。完整狀態碼表、重試規則與報障所需資訊見錯誤碼與重試。

網關按請求頭 Accept-Language 返回簡體中文、繁體中文、英文、日文或西班牙文文案，未指定時為英文；請求頭為 zh-TW 或 zh-HK 時返回各表引用的繁體原文。

金鑰、餘額與權限

現象原因怎麼做
401「缺少 API Key」
「API Key 無效」
「API Key 已過期」		沒帶金鑰、複製不完整或多了空格，或金鑰已刪除、停用、過期回控制台「API 金鑰」重新完整複製，必要時新建一把
402「餘額不足」
「API Key 配額已用完」
「成員額度已用盡」
「部門額度已用盡」		帳戶餘額、這把金鑰的額度、企業成員或部門額度不足充值或調整額度後再發；402 不會自行恢復，不要循環重試
影片提交返回 402「Insufficient balance: available …」影片任務提交時的餘額預留不足充值後再提交；不要循環重試
403「此帳號已被停用」
「此成員帳號已被停用」
「此成員無權使用此 API Key 所綁定的分組」
「API Key 未綁定任何分組，請聯絡管理員」
「目前分組未啟用圖片生成」		帳戶、成員或分組設定限制聯絡管理員；不要重試
404「此 API Key 所屬分組已下線，不再處理請求…」金鑰綁定的分組已下架在控制台用在售分組建立新金鑰並替換

模型與路徑

現象原因怎麼做
404「目前分組不支援所請求的模型：X」
「此 API Key 所屬分組未提供所請求的模型…」		模型 ID 不在這把金鑰的任何分組裡、拼寫不完整，或客戶端配置裡殘留已下架的 ID用該金鑰調 GET /v1/models 複製完整 ID；列表裡沒有就在控制台給金鑰加上該模型所在的分組；不要自動重試
404「目前平台不支援此 API 路徑」Claude 金鑰調了 OpenAI 協議接口Claude 改用 Anthropic 協議
同上Anthropic Base URL 多寫 /v1（變成 /v1/v1/messages）Base URL 不帶 /v1
同上調了平台不提供的接口，如 /v1/dashboard/billing/*、/v1/files、/v1/batches、/v1/embeddings查餘額用 GET /v1/usage 或控制台
同上Codex 聯網搜索調了 /v1/alpha/search這個 404 不影響對話
影片接口返回 404「目前平台不支援此 API 路徑」影片路徑寫錯按影片 API 用 POST /v1/video/generate 提交、GET /v1/video/tasks/{task_id} 查詢

請求內容

現象原因怎麼做
400「讀取請求主體失敗」
「請求主體必須為 JSON 物件，且欄位類型須正確」
「缺少必填欄位：model」
「messages 必須為非空陣列」		請求體不完整或欄位不合法檢查 JSON 與 Content-Type
413「請求主體超過大小限制（60 MB）」請求體超過 60 MB，多為 base64 圖片、影片大檔案先壓縮，或在模型支援時改傳 URL
400 輸入超出上下文長度（原文因模型而異）對話歷史、附件與 max_tokens 合計超過模型上下文裁剪歷史或開新會話，調小 max_tokens
400「Invalid signature in thinking block」
「duplicate thinking.signature」		Claude 的 thinking 歷史被改寫、拼接或重複原樣回傳上一輪 assistant 的 thinking 塊（含 signature），不要改寫、合併或跨模型複用；修不好就從不含 thinking 的歷史重新開始
400「No tool call found for function call output」
「No tool output found for function call」		工具結果與工具調用沒有成對：tool_call_id / call_id 對不上，或少了一方每個工具調用都回傳一條結果並原樣帶回 ID；刪歷史時成對刪除
400「Unsupported parameter: …」模型不接受某個參數刪掉該參數；Responses 接口限制輸出長度用 max_output_tokens，不要用 max_tokens

圖片與影片

現象原因怎麼做
400 內容被安全策略拒絕（如「Your request was rejected by the safety system.」）提示詞或參考素材觸發模型的內容安全策略修改提示詞或素材後再發，原樣重試仍會被拒
400 圖片參數錯誤（如「size … is not valid」）尺寸、檔位或張數不在該模型支援範圍按圖片 API 裡對應模型的取值修改
400「media_download_failed」參考圖片或影片的 URL 無法公開訪問換成不需要登入就能下載的 HTTP(S) URL
400「InputImageSensitiveContentDetected.PrivacyInformation」Seedance 2.0 對直接傳入的真人參考圖做隱私檢測先用 POST /v1/sd/assets 上傳為素材，再以 asset://素材ID 引用，詳見影片 API
非同步任務輪詢返回 status: "failed"（如「the prompt was rejected by content moderation; rephrase it and submit again」）原因在 error.message，無 code，不扣費按提示修改後再提交；見錯誤碼與重試
想知道某個非同步任務實際扣了多少任務結束後查詢回應裡就有讀根物件的 usage.cost_usd（從餘額扣除的美元金額）、usage.cost（同一筆的人民幣金額）與 usage.currency（未扣費的失敗為 0）；任務列表裡每個終態任務的 usage 也帶這些欄位，見影片 API

限流、超時與中斷

現象原因怎麼做
429「用戶並發已達上限，請稍後重試」
「API Key 並發已達上限，請稍後重試」		同時在途的請求超過帳戶或金鑰的並發上限在客戶端排隊限流，按回應頭 Retry-After 稍後再發；上限見並發、超時與計費
429「…目前受到速率限制，請稍後重試」
502「…服務暫時無法使用，請稍後重試」
503「目前沒有可用的…，請稍後重試」
503「請求暫時無法完成，請稍後重試」
504「…請求逾時，請稍後重試」
503「認證服務暫時無法使用，請重試」		服務暫時不可用或響應超時按 Retry-After 或指數退避重試，也可換同系列模型；持續超過 10 分鐘，帶上回應頭裡的 X-Request-ID 聯絡我們
503「本次對話綁定的有狀態工作階段已無法繼續…」原會話已無法接續去掉 previous_response_id 開新對話
請求中途斷開，記錄為 499客戶端在完成前主動斷開：手動中斷，或客戶端讀超時先到（openai-python 預設 600 秒，其他客戶端各不相同）長輸出改用串流，並調大客戶端讀超時
串流輸出到一半收到錯誤事件（如「Response stream interrupted, please retry」）或連線斷開已開始輸出後出錯，無法在同一條流裡續傳丟棄已收到的片段，整條請求重新發起

本機環境

現象原因怎麼做
「node / npm 不是內部或外部命令」Node.js 沒裝好或沒進 PATH到 nodejs.org 重裝（Windows 保持預設勾選），裝完關掉終端機重新開啟
PowerShell 提示「禁止執行指令碼」Windows 指令碼執行原則限制優先用控制台「一鍵接入」的命令；或以系統管理員執行 Set-ExecutionPolicy RemoteSigned

按表排查後仍未解決？請帶上客戶端名稱、模型 ID、發生時間、HTTP 狀態碼、回應頭裡的 X-Request-ID 和已隱藏金鑰的截圖，聯絡我們。

下一步

本頁目錄

金鑰、餘額與權限模型與路徑請求內容圖片與影片限流、超時與中斷本機環境下一步