錯誤排解指南：解決 SillyTavern（酒館）中的 TavernAPI 報錯

先檢查這 5 項基本設定

在逐一查詢錯誤碼之前，請先打開 SillyTavern（酒館）頂端的 API Connections 面板（插頭圖示），花 60 秒核對以下清單。絕大多數的連線問題，只要修正這裡的小地方就能馬上解決：

1. Chat Completion Source（對話補全來源）： 將 API 設為 Chat Completion，並將 Chat Completion Source 設為 Custom (OpenAI-compatible)。
2. Base URL（端點網址）： 將 Custom Endpoint (Base URL) 設為 https://tavernapi.com/v1，結尾不要加斜線 /，也不要加上 /chat/completions。
   • 網頁前端（JanitorAI）： 要求填入完整 Proxy 網址的瀏覽器前端是例外——請填入 https://tavernapi.com/v1/chat/completions。
   • SillyTavern 原生 Reverse Proxy（反向代理）： 如果你不是用 Custom，而是透過酒館的原生來源連線，選 Claude 來源時請將 Proxy Server URL 設為 https://tavernapi.com/v1；選 Google AI Studio 來源時則請設為 https://tavernapi.com。
3. API Key（API 金鑰）： 將完整的 sk-tav-... 字串貼入 Custom API Key（原生來源則貼入 Proxy Password），確認前後沒有多餘的空白字元。
4. 連線並選擇模型： 點一下 Connect（連線），接著從 Available Models 下拉選單挑選模型（claude-opus-5-5、claude-sonnet-5-5、gemini-4-argon、gemini-3.8-flash 或 deepseek-v4-pro）。
5. 帳號餘額： 打開 TavernAPI 控制台，確認你的美金可用餘額或 $0.30 免費試用額度大於零。

TavernAPI 的報錯在 SillyTavern 裡長怎樣？

當請求無法完成時，TavernAPI 會回傳以下標準結構的 JSON：

{"error": {"message": "...", "type": "...", "code": "..."}}

SillyTavern 會在紅色彈出通知中顯示 "message" 的內容。如果紅色通知消失得太快來不及看，可以切去執行酒館伺服器的黑色終端機視窗（Windows 的命令提示字元 CMD，或 Android 的 Termux），裡面會完整印出 HTTP 狀態碼與錯誤 "code"。

常見錯誤碼一覽

請對照下方的 HTTP 狀態碼與錯誤訊息，查看請求失敗的原因與修復步驟。

401 Invalid API key（API 金鑰無效）

• 畫面顯示： 訊息為 Invalid API key，錯誤碼為 invalid_api_key。如果完全沒有送出金鑰（金鑰欄位空白），訊息開頭會是 Missing API key，錯誤碼為 missing_api_key。
• 發生原因： API 金鑰欄位留空、sk-tav-... 金鑰在複製時漏了字元、前後不小心多貼了空白、該金鑰已在控制台被撤銷刪除，或是誤貼成其他平台的金鑰（例如 OpenRouter 或 OpenAI 的金鑰）。
• 解決方法： 重新完整複製並貼上你的 sk-tav-... 金鑰，並檢查前後是否有空白。如果手邊已經沒有完整金鑰字串，請打開控制台的 API 金鑰 分頁建立一組新金鑰（每組金鑰只會顯示一次，建立後請立即複製保存）。
• 會被扣費嗎？ 不會。

402 Insufficient balance（餘額不足）

• 畫面顯示： 訊息為 Insufficient balance，錯誤碼為 insufficient_balance。
• 發生原因： 你目前的可用餘額（或試用額度）低於啟動該次請求所需的「暫時預扣金額」。在轉發每次提示詞之前，TavernAPI 會先暫時凍結一筆預估費用，金額等於「可見輸入 Token 加上按模型輸出單價計算的完整 Max Response Length（max_tokens）」。一旦回覆生成結束，TavernAPI 只會扣除實際用掉的 Token 費用，並立即退還剩餘的預扣額度。因為有這道預授權機制，當你的 Max Response Length 設得非常高，或是正在呼叫單價較高的模型（如 claude-opus-5-5）時，就算帳號裡還剩一點餘額，也可能會跳出 402。
• 解決方法：
  1. 打開 SillyTavern 的 AI Response Configuration（頂端最左側的滑桿圖示），將 Max Response Length（最大回覆長度）調低到合理的數值（例如 1024 或 2048 Tokens），縮小每次請求前的預扣金額。
  2. 在模型下拉選單改用單價較親民的模型，例如 gemini-3.8-flash 或 deepseek-v4-pro（參見模型費率）。
  3. 或者前往控制台為帳號儲值。
• 會被扣費嗎？ 不會。

403 試用額度限制或預設尚未解鎖

• 畫面顯示： 以下三種 403 訊息與錯誤碼之一：
  • 試用模型限制： 訊息為 Model "<id>" is not available with trial credit. Add credit to unlock it.，錯誤碼為 trial_restricted。
  • 預設包尚未解鎖： 訊息為 "<preset pack name>" is not included in your account. See https://tavernapi.com/console/presets（或 This preset is currently unavailable），錯誤碼為 preset_locked。
  • 帳號狀態異常： 訊息為 Account suspended，錯誤碼為 account_banned。
• 發生原因：
  • trial_restricted：$0.30 免費試用額度僅支援 gemini-4-argon 與 gemini-3.8-flash。若在僅有試用額度的帳號上呼叫 claude-opus-5-5、claude-sonnet-5-5 或 deepseek-v4-pro，就會觸發此錯誤。
  • preset_locked：你目前在 SillyTavern 啟用的預設中，包含了帳號尚未解鎖的 [[tav:...]] 伺服器端預設佔位符。
  • account_banned：帳號已被停權（請參閱《使用規範》）。
• 解決方法：
  • 若是 trial_restricted： 在 SillyTavern 的模型下拉選單改選 gemini-4-argon 或 gemini-3.8-flash，或直接到控制台儲值以解鎖全部五款模型。
  • 若是 preset_locked： 在 SillyTavern 切換回你自己的本地預設、在 Prompt Manager（提示詞管理器）關掉鎖定的 [[tav:...]] 條目，或前往 https://tavernapi.com/console/presets 解鎖該預設包。Standard（標準版）預設會在首次儲值時自動解鎖；Pro（專業版）預設則可透過 $4.99 單次買斷、購買使用中的 $19 或 $39 額度包，或累計儲值滿 $25 解鎖（詳見 TavernAPI 預設運作原理）。
  • 若是 account_banned： 請附上你的帳號信箱聯絡客服。
• 會被扣費嗎？ 不會。

404 Model not available（找不到模型）

• 畫面顯示： 訊息為 Model "<id>" is not available，錯誤碼為 model_not_found。
• 發生原因： 請求中的模型 ID 拼字錯誤、殘留了其他平台的模型格式（例如 OpenRouter 的 anthropic/claude-... 前綴，或舊版的 -story 後綴），或是該模型目前暫時關閉維護中。
• 解決方法： 在 SillyTavern 點一下 Connect 重新整理模型下拉選單，並直接從選單中挑選。如果你是在需要手動輸入模型 ID 的介面（例如 JanitorAI），請填入以下五個確切 ID 之一：
  • claude-opus-5-5
  • claude-sonnet-5-5
  • gemini-4-argon
  • gemini-3.8-flash
  • deepseek-v4-pro
• 會被扣費嗎？ 不會。

404 Not found（網址路徑錯誤）

• 畫面顯示： 訊息為 Not found，錯誤碼為 not_found。
• 發生原因： 填入的 API 網址路徑有誤。最常見的情況是 /v1 重複貼了兩次（變成 https://tavernapi.com/v1/v1），或是在 SillyTavern 的 Custom Endpoint 欄位多貼了 /chat/completions（酒館會自己往後加 /chat/completions）。如果網址完全漏掉 /v1（只填 https://tavernapi.com），請求會直接連到官網首頁而非 API 伺服器，這時會收到一般網頁的 404 而非這段 JSON 報錯，但解法完全相同。
• 解決方法： 請對照先檢查這 5 項基本設定及下表，依你使用的前端換成正確網址：

• 會被扣費嗎？ 不會。

400 Bad request（請求格式錯誤）

• 畫面顯示： 以下三種 400 訊息與錯誤碼之一：
  • model is required（錯誤碼 model_required）
  • messages must be a non-empty array（錯誤碼 messages_required）
  • Unknown preset block [[tav:...]]. Download the latest preset from https://tavernapi.com/console/presets（錯誤碼 preset_block_unknown）
• 發生原因：
  • model_required：送出訊息前還沒有選擇任何模型。
  • messages_required：送出的請求陣列中沒有任何訊息（例如提示詞全空，或是被正則腳本／擴充插件把所有訊息都過濾掉了）。
  • preset_block_unknown：你本地的預設檔版本比伺服器目前的預設定義還舊，或是手動改到了 [[tav:...]] 標籤文字。
• 解決方法：
  • 若是 model_required，請在 SillyTavern 按一下 Connect 並從下拉選單選取模型。
  • 若是 messages_required，請確認對話視窗中至少有一則訊息，並檢查是否有會修改提示詞的擴充功能。
  • 若是 preset_block_unknown，請前往 https://tavernapi.com/console/presets 重新下載最新版預設 JSON 檔，再次匯入 SillyTavern。
• 會被扣費嗎？ 不會。

429 請求過於頻繁或上游線路忙碌

• 畫面顯示： 訊息為 Upstream error (429)，類型為 rate_limit_error，錯誤碼為 upstream_error。
• 發生原因： 你在短時間內同時送出了過多請求（例如上一輪還在生成時就連續狂按重新生成），或是上游模型供應商當下正處於尖峰滿載。當某條上游線路滿載時，TavernAPI 會先自動嘗試切換其他備援線路，全部滿載時才會回傳 429。
• 解決方法： 稍等幾秒鐘，再按右滑重骰（Swipe）或重新生成回覆。
• 會被扣費嗎？ 不會——只要沒有產生任何回覆，就不會扣款。

5xx 伺服器錯誤

• 畫面顯示：
  • HTTP 502：訊息為 Upstream error (502)，錯誤碼為 upstream_error
  • HTTP 503：訊息為 No upstream route is configured for this model，錯誤碼為 no_route
  • HTTP 500：preset_... 開頭的錯誤碼（例如 preset_block_error）
• 發生原因：
  • Upstream error (502)（upstream_error）：上游模型供應商無回應，或請求途中網路連線中斷。
  • No upstream route is configured for this model（503，no_route）：該模型的所有上游線路目前暫時無法使用。
  • 500 preset_... 錯誤碼（如 preset_block_error）：伺服器在展開鎖定的預設區塊時發生內部錯誤。
• 解決方法：
  • 若是 502（upstream_error）： 稍等幾秒鐘後再重骰或重新生成。
  • 若是 503（no_route）： 在線路恢復前，請先從下拉選單切換使用其他模型。
  • 若是 500（preset_block_error）： 請先試著不套用 TavernAPI 預設（或先關掉鎖定的 [[tav:...]] 條目）發送同一則對話，確認一般生成是否正常，接著附上大致發生時間與模型 ID 聯絡客服。
• 會被扣費嗎？ 如果上游在產生任何回覆文字前就失敗，預扣金額會全額退回；如果是在串流開始後生成到一半才中斷，則只會按實際已產生的 Token 計費。

沒有跳出錯誤碼的常見問題

有時候 SillyTavern 並沒有跳出紅色的 HTTP 錯誤通知，但聊天室裡的表現卻不太對勁。

按下 Connect 維持紅燈，或模型選單一片空白

如果在 SillyTavern 按下 Connect 後狀態燈依然是紅色，或是 Available Models 下拉選單裡空無一物：

1. 請照著先檢查這 5 項基本設定核對連線來源、Base URL 與 API 金鑰。
2. 確認網址開頭是 https://（不是 http://），且 https:// 前面與 /v1 後面都沒有多餘空白。
3. 如果你使用的是 SillyTavern 原生的 Claude 或 Google AI Studio 來源，請確認已展開下方的 Reverse Proxy 區塊，並將 sk-tav-... 金鑰貼在 Proxy Password 欄位，而不是貼在上方直連官方的 API Key 欄位。每個欄位的完整填法請參考 SillyTavern 串接教學。

AI 回覆空白，或句子講到一半斷掉

如果角色的訊息在句子中間突然截斷，或是回傳完全空白的對話框：

• Max Response Length 設得太低： 當回覆達到 SillyTavern AI Response Configuration 面板中的 Max Response Length（max_tokens）上限時，生成就會立刻停下。此外，具備「先思考再回答」機制的模型，會從這筆 Token 預算中先拿一部分去做內部推理，之後才開始寫出可見回覆。如果 Max Response Length 設得太低（例如只有 250 或 400），模型光在內部思考階段就會把額度用光，導致最後印出來的可見回覆變成空白。請把 Max Response Length 調高（例如設為 1024～2048 Tokens）再重新生成。
• 上游安全過濾： 當提示詞觸發上游模型商自家的安全分類器時，上游過濾器也可能會提前中斷回覆或回傳空白訊息。

回覆沒有套用預設規則，或直接印出 [[tav:...]] 文字

鎖定的預設佔位符（[[tav:...]]）只有在請求經過 TavernAPI 伺服器時才會自動展開。如果 AI 回覆完全無視預設規則，或你在畫面上直接看到未展開的 [[tav:...]] 字串：

1. 打開 API Connections（插頭圖示），確認目前連線的網址確實指向 https://tavernapi.com/v1，而不是切到了其他平台的 API 卻忘記把 TavernAPI 預設關掉。
2. 打開 AI Response Configuration（滑桿圖示），確認 Chat Completion Presets 下拉選單已選中 TavernAPI 預設，且裡面的核心提示詞條目都有打開。
3. 每當官方預設更新後，請前往 https://tavernapi.com/console/presets 重新下載最新預設 JSON 檔並匯入酒館，讓本地檔案與伺服器保持同步。詳見 TavernAPI 預設運作原理。

Token 費用比預期高出不少

在角色扮演中，SillyTavern 每一輪都會把整串聊天紀錄、角色卡與預設重新發送一次。TavernAPI 會在伺服器端透過自動提示詞快取大幅壓低這筆輸入成本，因此如果帳單突然比平常貴，通常都是因為提示詞快取未命中（Cache Miss）或上下文累積得太長：

• 休息一段時間後發送的第一則訊息： 上游模型商只會在停止互動後的幾分鐘內保留快取前綴。離開較長時間後回來聊的第一輪必須重新建立快取，因此費用會明顯高一點；但緊接著聊下去的第二輪開始，就會馬上掉回超低價的快取讀取費率。
• 修改了前面的舊訊息或更動了提示詞開頭： 編輯或刪除較早之前的對話、在聊天中途切換預設，或是在提示詞最前端放入隨機巨集（如 {{random}}、{{roll}}），都會改變提示詞前綴，迫使整段快取重新寫入。
• 未修剪的超長上下文： 即使快取正常生效，一場已經累積超過 100k Tokens 的長篇對話，每一輪的基礎費用自然還是會比 20k Tokens 的對話高。

歡迎閱讀我們的提示詞快取省錢指南了解維持高快取命中率的技巧，並隨時到控制台的 用量資訊 頁面查看每筆請求確切的輸入、快取與輸出 Token 數量。

儲值與付款問題

TavernAPI 的加密貨幣儲值透過 NOWPayments 結帳，支援 $6 到 $500 之間的美金整數金額（參見如何使用加密貨幣付款）。在控制台的 帳單明細 頁面中，每筆加密貨幣訂單會顯示五種狀態之一：處理中（Pending）、部分付款（Partially paid）、已付款（Paid）、已過期（Expired）或失敗（Failed）。

實際到帳金額少於訂單金額

這通常發生在你的交易所或錢包直接從轉帳金額中「內扣」了提幣手續費，而沒有把外加的手續費算上去。

• 訂單狀態會變更為「部分付款」（Partially paid），系統會自動按實際到帳金額的比例加進你的餘額。
• 若要補足差額，請直接在控制台重新建立一筆新的儲值訂單。
• 除非客服人員請你這麼做，否則請勿直接往舊的收款地址補轉第二筆款項。

訂單狀態顯示「已過期」（Expired）

未付款的加密貨幣訂單會在 1 小時後自動關閉，狀態變更為「已過期」（Expired）。如果你已經匯出款項，只是鏈上交易在超過 1 小時後才送達，系統依然會自動把款項加進你的餘額。

我的儲值還沒入帳

區塊鏈網路確認通常只需要幾分鐘，但若遇到鏈上擁塞或交易所批次出金較慢，可能會花上更長時間。一旦交易完成鏈上確認，控制台 帳單明細 頁面中的狀態就會自動更新。

如果過了約 30 分鐘狀態仍沒有任何變化，請準備以下資訊聯絡客服：

• 交易雜湊值（TXID）
• 你使用的幣種與區塊鏈網路
• 實際轉出的金額
• 你的 TavernAPI 帳號信箱

轉帳金額超過訂單金額

當實際轉帳金額超過訂單總額時，系統只會自動入帳訂單原本設定的金額，多付的部分不會自動加入。請附上你的交易雜湊值（TXID）與帳號信箱聯絡客服，我們核實款項後就會幫你把多出的金額補進餘額。

選錯了區塊鏈網路或幣種

如果你在轉帳時選錯了區塊鏈網路，或轉入了與結帳頁面所選不同的加密貨幣，請立即附上交易雜湊值（TXID）、幣種、網路與轉帳金額聯絡客服。此類跨鏈或錯幣轉帳無法保證一定能找回。

還是無法解決嗎？

如果以上步驟仍無法解決你的問題，歡迎透過聯絡我們頁面找我們，並附上以下資訊，方便我們第一時間幫你查閱紀錄：

• API 或預設報錯問題： 你的 TavernAPI 帳號信箱、使用的模型 ID（claude-opus-5-5、claude-sonnet-5-5、gemini-4-argon、gemini-3.8-flash 或 deepseek-v4-pro）、大致發生時間（請註明時區）、HTTP 狀態碼與錯誤 code，以及當時使用的預設包名稱（若有使用）。
• 儲值與付款問題： 你的帳號信箱、交易雜湊值（TXID）、使用的幣種與網路，以及轉出的金額。