本指南可協助您診斷及解決呼叫 Gemini API 時發生的常見問題。如果您遇到 API 金鑰問題，請務必根據 API 金鑰設定指南，正確設定 API 金鑰。
錯誤代碼
下表列出您可能會遇到的常見錯誤代碼，以及這些代碼的原因與疑難排解步驟：
| HTTP 程式碼 | 狀態 | 說明 | 解決方案 |
| 400 | INVALID_ARGUMENT | 要求主體格式錯誤。 | 如要瞭解要求格式、範例和支援的版本，請參閱 API 參考資料。如果使用包含舊版端點的新版 API 功能，可能會導致錯誤。 |
| 403 | PERMISSION_DENIED | 您的 API 金鑰沒有必要權限。 | 請確認 API 金鑰已設定完成，且有權存取。 |
| 404 | NOT_FOUND | 找不到要求的資源。 | 檢查要求中的所有參數是否皆有效適用於您的 API 版本。 |
| 429 | RESOURCE_EXHAUSTED | 您已超過頻率限制， | 確認您符合模型的頻率限制。如有需要，請要求提高配額。 |
| 500 | INTERNAL | Google 端發生未預期的錯誤， | 請稍後再重試要求。如果重試後問題仍未解決，請使用 Google AI Studio 中的「提供意見」按鈕來回報問題。 |
| 503 | UNAVAILABLE | 服務可能會暫時超載或停止運作。 | 請稍後再重試要求。如果重試後問題仍未解決，請使用 Google AI Studio 中的「提供意見」按鈕來回報問題。 |
查看 API 呼叫中的模型參數錯誤
請確認您的模型參數位於下列值內：
| 模型參數 | 值 (範圍) |
| 候選數量 | 1 至 8 (整數) |
| 溫度 | 0.0-1.0 |
| 輸出內容符記數量上限 |
請使用 get_model (Python) 決定所用模型的權杖數量上限。 |
| TopP | 0.0-1.0 |
除了檢查參數值之外，請確認您使用的 API 版本正確無誤 (例如/v1 或 /v1beta) 和支援所需功能的模型。舉例來說，如果功能仍為 Beta 版，則只能在 /v1beta API 版本中使用。
檢查您使用的模型是否正確
確認您使用的是支援的模型。使用 list_models (Python) 即可取得可以使用的所有模型。
安全性問題
如果您看到提示因 API 呼叫中的安全設定而遭到封鎖，請根據您在 API 呼叫中設定的篩選條件查看提示。
如果您看到 BlockedReason.OTHER，表示查詢或回應可能違反服務條款或不受支援。
改善模型輸出內容
如要提高模型輸出內容的品質，請編寫更多結構化提示。提示設計簡介頁面會介紹一些基本概念、策略和最佳做法，協助您快速上手。
如果您有數百個良好的輸入/輸出組合範例，也可以考慮調整模型。
瞭解權杖限制
使用 ModelService API 取得模型的其他中繼資料，包括輸入和輸出權杖限制。
如要取得提示使用的權杖，請使用 countMessageTokens 處理聊天模型，並將 countTextTokens 用於文字模型。
已知問題
- Google AI Studio 行動裝置支援：雖然您可以在行動裝置上開啟網站，但網站並未針對小螢幕進行最佳化調整。
- API 只支援英文。以不同語言提交提示可能會導致意外回應，甚至遭到封鎖。如需更新內容，請參閱支援的語言。
回報錯誤
在 GitHub 中提出問題或提交功能要求或錯誤。