API 錯誤

本頁面提供 GenerateContent API 傳回的後端錯誤代碼參考資料，說明 gRPC 錯誤回應格式，並提供疑難排解步驟。

HTTP 錯誤代碼

下表列出常見的後端錯誤代碼、原因說明和建議解決方案：

HTTP 程式碼 狀態 說明 範例 解決方案
400 INVALID_ARGUMENT 要求主體格式錯誤。 要求中有錯別字，或缺少必填欄位。 請參閱 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 您已超過其中一項 API 使用頻率限制 (RPM、TPM、RPD、支出等)。 您傳送的要求過多、使用的符記過多，或超出帳戶帳單記錄和層級的支出限制。 確認您未超出模型的速率限制。請稍候片刻再重試。降低要求速率或縮減要求大小。如有需要，請要求提高速率限制。
499 已取消 作業已取消 (通常由呼叫端取消)。 API 尚未完成回應，用戶端就已關閉連線。 檢查用戶端或網路基礎架構是否過早關閉連線 (例如因用戶端逾時)。
500 內部資源 Google 發生未預期的錯誤。 輸入內容過長。 查看 Gemini API 狀態頁面，瞭解是否有任何進行中的事件。縮減輸入內容的脈絡，或暫時改用其他模型 (例如從 Gemini 2.5 Pro 改用 Gemini 2.5 Flash)，看看是否能解決問題。或者稍後再試一次。如果重試後問題仍未解決，請使用 Google AI Studio 的「提供意見」按鈕回報。
503 無法使用 該服務可能暫時超載或關閉。 這項服務的容量暫時不足。 查看 Gemini API 狀態頁面，瞭解是否有任何進行中的事件。暫時切換至其他模型 (例如從 Gemini 2.5 Pro 切換至 Gemini 2.5 Flash)，看看是否能正常運作。或者稍後再試一次。如果重試後問題仍未解決，請使用 Google AI Studio 的「提供意見」按鈕回報。
504 DEADLINE_EXCEEDED 服務無法在期限內完成處理。 提示 (或情境) 過大，無法及時處理。 在用戶端要求中設定較大的「逾時」，即可避免這個錯誤。

錯誤回應格式

如果 GenerateContent 要求失敗，API 會設定 HTTP 狀態碼 (例如 400 Bad Request、403 Forbidden 或 429 Too Many Requests)，並傳回包含 gRPC 狀態詳細資料的 JSON 回應主體：

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
欄位 類型 說明
code 整數 HTTP 狀態碼。
message 字串 使用者容易理解的錯誤說明。
status 字串 SCREAMING_CASE 中的 gRPC 狀態碼。
details 陣列 其他錯誤脈絡，例如 ErrorInfo 或 LocalizedMessage。

後續步驟