本指南可協助您診斷及解決呼叫 Gemini API 時發生的常見問題。您可能會遇到 Gemini API 後端服務或用戶端 SDK 的問題。我們的用戶端 SDK 採用開放原始碼，位於下列存放區：
python-genai
js-genai
go-genai
如果遇到 API 金鑰問題，請按照
API 金鑰設定指南
，確認您已正確設定 API 金鑰。
Gemini API 後端服務錯誤代碼
下表列出您可能遇到的常見後端錯誤代碼，並說明原因和疑難排解步驟：
HTTP 程式碼
FAILED_PRECONDITION
你所在的國家/地區不支援 Gemini API 免費方案。請在 Google AI Studio 中啟用專案的計費功能。
您在不支援免費層級的區域提出要求，且尚未在 Google AI Studio 中為專案啟用帳單。
如要使用 Gemini API，請透過
Google AI Studio
設定付費方案。
PERMISSION_DENIED
您的 API 金鑰沒有必要權限。
您使用的 API 金鑰有誤；您嘗試使用微調模型，但未經過
適當的驗證
。
確認 API 金鑰已設定且具有適當的存取權。請務必完成適當的驗證程序，才能使用微調模型。
NOT_FOUND
找不到要求的資源。
系統找不到要求中參照的圖片、音訊或影片檔案。
檢查要求中的所有
參數是否適用於您的 API 版本
。
RESOURCE_EXHAUSTED
你已超過速率限制。
您使用免費層級的 Gemini API 時，每分鐘傳送的要求過多。
確認您未超出模型的
速率限制
。如有需要，請
申請提高配額
。
INTERNAL
Google 發生未預期的錯誤。
輸入內容過長。
減少輸入內容的脈絡，或暫時切換至其他模型 (例如從 Gemini 1.5 Pro 切換至 Gemini 1.5 Flash)，看看是否能解決問題。或是稍後再試一次。如果重試後問題仍未解決，請使用 Google AI Studio 的「提供意見」
按鈕回報問題。
該服務可能暫時超載或關閉。
這項服務的容量暫時不足。
暫時切換至其他模型 (例如從 Gemini 1.5 Pro 切換至 Gemini 1.5 Flash)，看看是否能正常運作。或是稍後再試一次。如果重試後問題仍未解決，請使用 Google AI Studio 的「提供意見」
按鈕回報問題。
DEADLINE_EXCEEDED
服務無法在期限內完成處理。
提示 (或情境) 過大，無法及時處理。
在用戶端要求中設定較大的「逾時」，即可避免這個錯誤。
檢查 API 呼叫是否有模型參數錯誤
確認模型參數是否在下列值範圍內：
值 (範圍)
除了檢查參數值，請務必使用正確的
API 版本
(例如
/v1
或
/v1beta
)，以及支援所需功能的機型。舉例來說，如果某項功能為 Beta 版，則僅適用於
/v1beta
API 版本。
確認你是否使用正確的機型
確認您使用的是
模型頁面
上列出的支援模型。
使用 2.5 模型時延遲時間較長或權杖用量較高
如果使用 2.5 Flash 和 Pro 模型時，發現延遲時間較長或權杖用量較高，可能是因為這些模型
預設啟用思考功能
，以提升品質。如果想優先提升速度或盡量降低成本，可以調整或停用思考功能。
如需指引和程式碼範例，請參閱
思考頁面
。
如果系統顯示因 API 呼叫中的安全設定而封鎖提示，請根據您在 API 呼叫中設定的篩選條件檢查提示。
如果看到
BlockedReason.OTHER
，表示查詢或回覆可能違反《
服務條款
》或不受支援。
引用內容侵權
如果模型因「RECITATION」原因停止生成輸出內容，表示模型輸出內容可能與特定資料相似。如要修正這個問題，請盡量讓提示 / 情境獨一無二，並使用較高的溫度。
重複權杖問題
如果看到重複的輸出權杖，請嘗試下列建議，減少或消除這些權杖。
Markdown 表格中重複的連字號
如果表格內容很長，模型會嘗試建立視覺上對齊的 Markdown 表格，這時就可能發生這種情況。不過，Markdown 中的對齊方式並非正確算繪的必要條件。
在提示中加入指令，為模型提供生成 Markdown 表格的具體指引。請提供符合這些規範的範例。你也可以嘗試調整溫度。如要生成程式碼或 Markdown 表格等結構化輸出內容，高溫參數 (>= 0.8) 的效果較好。
以下是可新增至提示的範例規範，有助於避免這個問題：
# Markdown Table Format
* Separator line: Markdown tables must include a separator line below
the header row. The separator line must use only 3 hyphens per
column, for example: |---|---|---|. Using more hypens like
----, -----, ------ can result in errors. Always
use |:---|, |---:|, or |---| in these separator strings.
For example:
| Date | Description | Attendees |
|---|---|---|
| 2024-10-26 | Annual Conference | 500 |
| 2025-01-15 | Q1 Planning Session | 25 |
* Alignment: Do not align columns. Always use |---|.
For three columns, use |---|---|---| as the separator line.
For four columns use |---|---|---|---| and so on.
* Conciseness: Keep cell content brief and to the point.
* Never pad column headers or other cells with lots of spaces to
match with width of other content. Only a single space on each side
is needed. For example, always do "| column name |" instead of
"| column name |". Extra spaces are wasteful.
A markdown renderer will automatically take care displaying
the content in a visually appealing form.
When thinking silently: ALWAYS start the thought with a brief
(one sentence) recap of the current progress on the task. In
particular, consider whether the task is already done.
除非另有註明，否則本頁面中的內容是採用
創用 CC 姓名標示 4.0 授權
，程式碼範例則為
阿帕契 2.0 授權
。詳情請參閱《
Google Developers 網站政策
》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-22 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-08-22 (世界標準時間)。"],[],[],null,[]]
