本指南可協助您診斷並解決 呼叫 Gemini API 時大致上，您可能會遇到 Gemini API 後端服務或用戶端 SDK我們的用戶端 SDK 開放原始碼的原始碼：
- generative-ai-python
- generative-ai-js
- generative-ai-android
- generative-ai-swift
- generative-ai-dart
- generative-ai-go
如果您遇到 API 金鑰問題，請確認您已完成設定 按照 API 金鑰設定指南正確設定 API 金鑰。
Gemini API 後端服務錯誤代碼
下表列出您可能會遇到的常見後端錯誤代碼，以及 並提供原因和疑難排解步驟：
| HTTP 代碼 | 狀態 | 說明 | 範例 | 解決方案 |
| 400 | INVALID_ARGUMENT | 要求主體格式錯誤。 | 要求中有錯字或必填欄位未填寫。 | 如要瞭解要求格式、範例和支援的版本，請參閱 API 參考資料。在舊版端點上使用新版 API 的功能可能會造成錯誤。 |
| 400 | FAILED_PRECONDITION | Gemini API 免費方案不適用於你的國家/地區。請在 Google AI Studio 中啟用專案的計費功能。 | 您提出要求的區域不支援免費方案，且您尚未在 Google AI Studio 中為專案啟用帳單功能。 | 如要使用 Gemini API，請務必透過 Google AI Studio 設定付費方案。 |
| 403 個 | PERMISSION_DENIED | 您的 API 金鑰沒有必要權限。 | 您使用的 API 金鑰有誤；你 嘗試使用調整後的模型，但未進行適當驗證。 | 請確認 API 金鑰已設定完成，且具備適當的存取權。此外，請務必完成適當的驗證，才能使用調整後的模型。 |
| 404 年 | NOT_FOUND | 找不到要求的資源。 | 找不到要求中參照的圖片、音訊或影片檔案。 | 檢查要求中的所有參數是否適用於您的 API 版本。 |
| 429 人 | RESOURCE_EXHAUSTED | 你的比率已超出上限。 | 使用免費方案 Gemini API 時，您每分鐘傳送的要求數量過多， | 確認您符合模型的頻率限制。如有需要，您可以申請提高配額。 |
| 500 人 | INTERNAL | Google 端發生未預期的錯誤， | 您輸入的背景資訊過長。 | 減少輸入內容或暫時切換至其他模型 (例如從 Gemini 1.5 Pro 改用 Gemini 1.5 Flash)，看看模型是否可行。或是稍後再重新提出要求。如果重試後問題仍未解決，請使用 Google AI Studio 中的「提供意見」按鈕回報問題。 |
| 503 | 無法使用 | 服務可能會暫時超載或停機。 | 服務暫時用盡， | 請暫時切換至其他模型 (例如從 Gemini 1.5 Pro 改為 Gemini 1.5 Flash)，看看模型是否能正常運作。或是稍後再重新提出要求。如果重試後問題仍未解決，請使用 Google AI Studio 中的「提供意見」按鈕回報問題。 |
| 504 人 | DEADLINE_EXCEEDED | 服務無法在期限內完成處理作業。 | 提示 (或內容) 過大，無法及時處理。 | 設定較大的「逾時」值以避免發生此錯誤。 |
Python 用戶端 SDK 錯誤代碼
下表列出常見的 Python 用戶端 SDK 錯誤 可能出現的代碼及其原因說明：
| 例外狀況/錯誤類型 | 類別 | 說明 |
|---|---|---|
| BlockedPromptException | google.generativeai.types.BlockedPromptException | 基於安全考量，提示遭到封鎖。 |
| BrokenResponseError | google.generativeai.types.BrokenResponseError | 串流回應損毀。會在存取需要完整回覆的內容 (例如即時通訊記錄) 時引發。查看堆疊追蹤中提供的錯誤詳細資料。 |
| IncompleteIterationError | google.generativeai.types.IncompleteIterationError | 如果存取的內容需要完整的 API 回應，但串流回應尚未完全疊代，就會引發這個錯誤。在回應物件上呼叫 resolve() 以使用疊代器。 |
| StopCandidateException | google.generativeai.types.StopCandidateException | API 傳回例外狀況的 finish_reason。請查看原因，瞭解如何繼續操作。 |
| PermissionDenied | google.api_core.exceptions.PermissionDenied | 您的權限不足，無法存取要求的資源 (例如模型)。 |
| ResourceExhausted | google.api_core.exceptions.ResourceExhausted | 配額已用盡，請稍後再試。建議您設定自動重試功能來處理這些錯誤。 |
| AlreadyExists | google.api_core.exceptions.AlreadyExists | 已有 ID 相同的調整後模型。調整新模型時，請指定不重複的模型 ID。 |
| InvalidArgument | google.api_core.exceptions.InvalidArgument | 引數無效，其中一個例子是檔案過大，超過酬載大小上限。另一個優惠是提供的 API 金鑰無效。 |
| DefaultCredentialsError | google.auth.exceptions.DefaultCredentialsError | 驗證失敗。請仔細檢查 API 金鑰，然後再試一次。 |
| RetryError | google.api_core.exceptions.RetryError | 這可能是因為使用的 Proxy 不支援 gRPC。請嘗試搭配 genai.configure(..., transport="rest") 使用 REST 傳輸。 |
檢查 API 呼叫是否有模型參數錯誤
請確認模型參數位於下列值內：
| 模型參數 | 值 (範圍) |
| 候選人數量 | 1-8 (整數) |
| 溫度 | 0.0 至 1.0 版 |
| 輸出符記數量上限 |
使用
get_model (Python)
來判斷所用模型的符記數量上限。
|
| TopP | 0.0 至 1.0 版 |
除了檢查參數值之外，也請確認您使用正確的
API 版本 (例如/v1 或 /v1beta) 和
支援您需要的功能舉例來說，假設某項功能仍為 Beta 版
版本，只有 /v1beta API 版本提供此版本。
確認是否有合適的模型
請確認您使用的是 Google Cloud 支援的模型 模型頁面。
安全問題
如果提示訊息因 API 呼叫中安全性設定而遭到封鎖， 查看您在 API 呼叫中設定的篩選器相關提示。
如果看到「BlockedReason.OTHER」，表示該查詢或回應可能違反相關條款
或不受支援。
引用問題
如果您發現模型因 RECITATION 而停止產生輸出內容， 表示模型的輸出內容可能會類似特定資料如要解決這個問題，請嘗試 盡量提供獨特的提示 / 情境，並提高隨機性參數
改善模型輸出內容
想取得更高品質的模型輸出內容，不妨瞭解如何撰寫更有條理的提示。 「提示設計簡介」頁面 一些基本概念、策略和最佳做法，協助您快速上手。
如果有數百種良好的輸入/輸出組合範例 考慮調整模型。
瞭解符記限制
詳閱權杖指南，進一步瞭解 計算符記及其限制
已知問題
- 這個 API 僅支援部分語言。在以下位置提交提示： 但可能會產生非預期的回覆，甚至遭到封鎖。詳情請見 支援的語言，以便進行更新。
回報錯誤
前往 Google AI 開發人員論壇參與討論 。