錯誤代碼與排解

先記錄發生時間、HTTP 狀態碼、模型、端點和請求 ID。隱藏 API Key 後再提交排解。

常見狀態碼

狀態碼	常見原因	建議處理
400	JSON、參數或請求內容格式錯誤	對照端點範例，檢查 model、stream 與 Content-Type
401	未帶 Key、Key 錯誤或已失效	重新建立/設定 Key，檢查驗證標頭
403	帳號、專案或上游權限不足	更換支援此能力的模型或聯絡管理員
404	路徑錯誤、模型不存在或平台不支援端點	檢查 /v1 是否重複，重新取得模型清單
409	請求狀態衝突	避免重複提交，依回應說明處理
429	並行、速率、模型容量或上游限流	遵守 Retry-After，退避重試或稍後再試
500	閘道內部異常	保留請求 ID，稍後重試並回報
502	上游回傳無效回應或連線失敗	稍後重試；持續發生時回報請求 ID
503	沒有相容可用帳號或服務暫時不可用	更換模型、稍後重試或聯絡管理員
504	上游逾時	降低請求複雜度或延長用戶端逾時

Selected model is at capacity

表示該模型目前沒有可立即處理請求的相容上游帳號，通常與帳號池繁忙、限流視窗或容量有關，而不是本機設定檔損壞。

1. 等待數秒後按指數退避重試。
2. 確認模型仍在 /v1/models 中。
3. 有替代模型時暫時切換。
4. 持續發生時提供時間、模型與請求 ID 給管理員。

首 Token 時間偏高

首 Token 時間包括網路連線、排隊、帳號選擇、上游握手、模型推理前置處理和工具準備。

• 使用串流回應改善使用者感受。
• 避免每次請求都攜帶過大的上下文。
• 比較關閉超高 reasoning effort 後的結果。
• 連續測試並觀察 P50/P95，不要只看一次請求。
• 區分「連線建立慢」與「上游模型開始輸出慢」。

生成圖片但用戶端不顯示

先查看原始 JSON。存在 b64_json 代表生成成功，問題在用戶端顯示；完全沒有圖像欄位則檢查模型、群組與請求格式。參見圖像生成與編輯。