官方免費額度查詢與模型分類 每日更新 最近更新：2026/10/22

常見觸發情境

• GenerateContent request body 格式錯誤、JSON 結構不符、欄位拼錯或漏掉必要欄位（如 contents）。
• 使用舊版 endpoint 呼叫較新版本才支援的功能，或把不支援的欄位／功能送給所選模型。
• 生成參數不合規。官方 troubleshooting 列有 Candidate count 1–8、Temperature 0.0–1.0、TopP 0.0–1.0 的檢查值。
• 多模態內容的欄位、Base64 bytes、MIME type 或模型能力不相符時，請依該方法的 API schema 查證。

逐步排查

1. 保留回應本文，檢查 error.message 和 error.details 指向的欄位；對照目前 API reference 的 request body。
2. 核對 URL 中模型 ID、HTTP 方法及 API 版本；確認所選模型支援所需功能及輸入類型。
3. 逐項驗證必填欄位、型別、參數範圍、媒體 MIME 與資料完整性。不要把其他模型的參數設定直接複製過來。
4. 辨別 400 FAILED_PRECONDITION 與 400 INVALID_ARGUMENT；兩者根因不同。

重試／備援：未修改請求前不要退避重試；換模型通常不會修正錯誤 JSON 或不合法參數。先修正 payload，再重新發送。

官方參考：GenerateContent 錯誤表 · 參數排查

常見觸發情境

• Interactions API 請求未提供、提供無效或已過期的 API key。
• 部署環境讀取到空白、被截斷、錯專案或已撤銷的 secret；也可能因 key 管理政策或限制而無法使用。
• GenerateContent 的官方錯誤本文範例把無效 API key 顯示為 400 INVALID_ARGUMENT 並附 API_KEY_INVALID。

逐步排查

1. 確認呼叫端使用正確 API 與專案的 key；REST 請求依文件透過 x-goog-api-key 傳送。
2. 在 Google AI Studio 核對 key 狀態、key 類型及限制；確定限制允許 Gemini API。
3. 若 key 已外洩、封鎖或失效，建立新 key、以安全 secret 更新後驗證，再停用舊 key。切勿把 key 放入公開前端、Git、截圖或日誌。

重試／備援：原樣重送或改模型都不會修復認證。先修復 key／環境設定，再測試。

官方參考：Interactions API 錯誤碼 · API key 安全指南

常見觸發情境

• 使用錯誤專案的 key，或該 key 沒有呼叫 Gemini API 所需的存取權。
• API key 的 API 限制不允許 Generative Language API，或專案／資源存取設定不符。
• 呼叫 tuned model 時未使用該模型要求的正確驗證或存取方式。

逐步排查

1. 檢查 error.message、error.status 與 details，確認拒絕的是哪個 key、project、model 或 resource。
2. 在 AI Studio／Cloud 專案核對 key、專案歸屬與 API 限制，確認模型及請求方法允許目前的認證。
3. 若 key 被標示封鎖或疑似外洩，依官方流程輪替 key 並稽核用量。

重試／備援：官方將 403 視為需先修正權限的客戶端錯誤，不建議原樣重試。

官方參考：GenerateContent 403 說明 · API key 與限制

常見觸發情境

• 指定的模型資源名稱或 endpoint 路徑拼寫錯誤，該模型亦可能已不在目前可用清單。
• GenerateContent request 引用不存在或不可取得的圖片、音訊、影片等檔案資源。
• 使用的 API 版本、方法或參數與該模型資源不相符。

逐步排查

1. 檢查錯誤本文中的 resource name；GenerateContent REST 路徑格式為 /v1beta/models/{model}:generateContent。
2. 呼叫 Models API 的 models.list / models.get 確認模型目前存在，並檢查 supported_actions。
3. 若錯誤指向媒體檔案，確認 file URI／資源 ID 有效。

重試／備援：未改路徑、資源或模型前重試不會修復 404。

官方參考：GenerateContent 404 說明 · Models API

常見觸發情境

• 超過該 project／model 適用的 RPM、輸入 TPM、RPD。
• 達到適用於帳戶或用量層級的 spend-based limit。
• 預覽／實驗模型或專案 tier 的限額較低。

逐步排查

1. 到 Google AI Studio 的 Active rate limits 查看當前 project 與 model 的限制。
2. 依回應訊息判斷 RPM、TPM、RPD 問題；降併發、節流、排隊。
3. 若是 RPD 用盡，依官方說明在美國太平洋時間午夜重設。

重試／備援：對可恢復的短暫限流使用有限次 exponential backoff + jitter；確認替代模型相容時才嘗試切換。

官方參考：Rate limits 與重設時間 · Retry strategy

建議處理

1. 檢查 Gemini API 狀態頁是否有事件，記錄時間、模型與錯誤本文。
2. 若 prompt／context 或多模態輸入很大，依該模型的限制精簡內容。
3. 稍候再有限重試；加入 exponential backoff 與 jitter。

重試／備援：Google 官方建議可等待後重試，或暫時切換另一個相容模型測試。

官方參考：GenerateContent 500 指引 · Gemini API status

建議處理

1. 先查看 API status page；核對是否其實收到 429 配額錯誤。
2. 等待短時間後進行有限退避重試，增加 jitter。
3. Google 官方建議可暫時嘗試另一個模型。

重試／備援：可把 503 視為暫時性錯誤進行有限 backoff；切換模型只是暫時排障方案。

官方參考：GenerateContent 503 指引 · Gemini API status

逐步排查

1. 分辨 deadline 是由 client、SDK、HTTP proxy 還是 API 回應產生。
2. 縮短 prompt/context、對話歷史或不必要的媒體輸入。
3. 若應用允許等待，可合理調高 client request timeout。

重試／備援：只對判定為暫時性的逾時有限重試，採 backoff 與 jitter。

官方參考：GenerateContent 504 指引 · 逾時與重試排查