錯誤代碼排錯
測連失敗或聊天氣泡報錯時，點 查看詳情，對照本頁的錯誤代碼（或文案關鍵詞）。
詳情一般包含：
- 錯誤代碼（英文標識，如
invalidApiKey） - 錯誤原因
- 嘗試修復
下列「代碼」以 App 錯誤詳情裡展示的名稱為準。
快速對照表
| 錯誤代碼 | 用戶可見摘要 | 優先處理 |
|---|---|---|
missingApiKey | 請先填寫 API 密鑰 | 模型連接裡填寫密鑰 |
invalidApiKey | 密鑰無效或過期 | 檢查複製是否完整；控制台重新生成 |
forbidden | 訪問被拒絕 | 權限、模型是否開通 |
regionForbidden | 地區不可用 | 換網絡 / 代理 / 國際站 |
network | 網絡連接失敗 | 網絡、Base URL、防火牆 |
timeout | 請求超時 | 網絡；本地模型加大超時 |
modelNotFound | 模型不存在 | 核對模型 ID |
modelRetired | 模型已下線 | 從列表改選當前可用模型 |
rateLimit | 過於頻繁 | 等待後重試 |
freeTierQuota | 免費檔請求配額 | 按 Please retry in … 等待；降低頻率或升級付費檔 |
insufficientQuota | 額度不足 | 充值 / 換密鑰 |
spendingCapExceeded | 月度消費上限 | 控制台提高 spend cap |
providerReturnedError | 上游返回錯誤 | 換模型 / 避開同廠商 :free / OpenRouter BYOK |
contextLengthExceeded | 上下文超限 | 降記憶；回覆令牌設 None；換大上下文模型 |
anthropicMaxTokensRequired | Claude 缺 max_tokens | 模型設置開啟「回覆令牌」 |
badRequest | 參數有誤 | 檢查參數與兼容接口格式 |
serverError | 服務端錯誤 | 稍後重試 |
requestFailed | 請求失敗 | 看詳情原文 |
contentPolicy | 安全審核未通過 | 重生成 / 換模型 / 改寫 |
emptyContent | 回覆為空 | 重試；檢查思考模型字段 |
modelAtCapacity | 模型滿載 | 等待或換模型 |
productNotActivated | 產品未開通 | 控制台開通模型 |
visionUnsupported | 不支持圖片 | 換視覺模型或關附圖 |
textOutputUnsupported | 不支持文字對話 | 改選文本聊天模型，勿選 TTS/生圖專用 ID |
分類詳解
missingApiKey
- 現象：未填密鑰無法請求。
- 處理：設置 → 模型連接 → 填寫 API 密鑰。本地 Ollama 等可填佔位字符（若校驗非空）。
invalidApiKey
- 現象：401 類、密鑰無效。
- 處理：無空格完整複製；確認國內/國際站與密鑰匹配；重新生成密鑰。
forbidden / regionForbidden
- 現象：403、地區限制。
- 處理：確認模型權限；換代理或國際站 Base URL。
network / timeout
- 現象：連不上或長時間無響應。
- 處理：
- 檢查 Base URL（本地勿用手機上的
localhost，用電腦局域網 IP）。 - 電腦防火牆放行端口；手機與電腦同一 Wi‑Fi。
- 弱網或本地慢模型：增大超時、換小模型。
- 檢查 Base URL（本地勿用手機上的
modelNotFound
- 現象：模型 ID 錯誤。
- 處理：測連後從列表重選；本地與
ollama list/ LM Studio 顯示名一致。
modelRetired
- 現象：HTTP 404，文案含
no longer available to new users/use a newer model（如models/gemini-2.5-flash-lite）。 - 區別：模型已被服務商停用或不再向新用戶開放，不是拼寫錯誤。
- 處理：模型連接里拉取最新列表，改選仍在線的 Gemini（如
gemini-flash-latest）。不必改用 Interactions API。目錄：Gemini models。
rateLimit
- 處理：降低發送頻率；稍後重試；升級套餐。
freeTierQuota
- 現象：Gemini 等返回
HTTP 429+generate_content_free_tier_requests（常見 limit: 20），並提示Please retry in …s。 - 區別：這是免費檔每分鐘/每天請求次數，不是賬戶沒錢，也不是項目月度 spend cap。
- 處理：等待提示秒數後重試；降低發送頻率；到 AI Studio 用量 查看；需要更高限額則開通結算/升級付費檔。說明：Gemini rate limits。
insufficientQuota / spendingCapExceeded
- 區別：額度用盡 vs 項目月度消費上限（後者稍後重試通常無效）。
- 處理：充值；或到控制台調整 spend cap（如 Google AI Studio Spend 頁）。
providerReturnedError
- 現象：OpenRouter 等返回
HTTP 429: Provider returned error（:free模型常見）。 - 處理：稍後重試；換其他廠商空閒模型；或 OpenRouter BYOK。
contextLengthExceeded
- 處理：設置 → 模型設置 → 減小記憶長度；將「回覆令牌」設為 None（若適用）；換更大上下文模型。
anthropicMaxTokensRequired
- 處理：Claude 必須帶 max_tokens → 模型設置中開啟「回覆令牌」，不要設為 None。
badRequest
- 處理：檢查 temperature 等參數；第三方兼容站是否真兼容 OpenAI/Anthropic 格式。
serverError / requestFailed / modelAtCapacity
- 處理：稍後重試；換端點或模型；持續失敗聯繫服務商並附詳情原文。
contentPolicy
- 處理：重生成、改寫、換審核更松的模型；部分 NSFW 卡易觸發輸出攔截。
emptyContent
- 處理：重試；部分思考模型只返回 reasoning → 看詳情中的完整字段或換模型。
productNotActivated
- 處理：雲廠商控制台開通對應產品/模型後再用當前密鑰。
visionUnsupported
- 處理：換支持視覺的模型；或不要發圖 / 開啟識圖描寫流程改用純文本描寫。
textOutputUnsupported
- 現象：HTTP 400，文案含
response modalities且TEXT不受支持（如models/gemini-2.5-flash-preview-tts只接受AUDIO）。 - 區別：選了語音合成 / 生圖等專用模型做聊天測連，不是密鑰或採樣參數填錯。
- 處理：模型連接裡改選文本聊天模型（如
gemini-flash-latest）。不要選名稱帶tts、image的專用 ID。語音、生圖請到對應功能裡配置。
本地模型專項
連不上電腦上的 Ollama / LM Studio：見 本地模型排錯。
App 測連 / 聊天報錯（含錯誤代碼）：見 使用手冊 · 錯誤代碼排錯。
截圖
