Gemini API 429 錯誤怎麼解決：RESOURCE_EXHAUSTED 的原因與 400 / 403 / 503 排查表

本文根據 Gemini API 官方文檔（API errors 的 Interactions 版與 generateContent 版、Troubleshooting guide、Rate limits、Billing）整理，資料核對於 2026-10-10。

適用於誰

• 調用 Gemini API 時遇到 429、RESOURCE_EXHAUSTED、rate_limit_exceeded、quota_exceeded 的人；
• 剛開始用、請求沒發幾個就被拒的人；
• 批量跑任務，想寫一個靠譜重試邏輯的開發者；
• 遇到 400、403、503 等其他錯誤，想快速對照官方說明的人。

結論先說

1. 429 的意思是超過了某一項限額，官方列的有每分鐘請求數（RPM）、每分鐘 token 數（TPM）、每天請求數（RPD），付費層還有按 10 分鐘計的支出速率上限。
2. 先分清是「每分鐘」還是「每天」：每分鐘類的等一會兒、降速重試就能恢復；每天的配額用完了，重試沒用，只能等重置（太平洋時間午夜）或升檔。
3. 限額按項目計算，不按密鑰。換一把同項目的密鑰解決不了問題。
4. 重試用指數退避加隨機抖動，並限制次數。官方 Python SDK 預設已經會自動重試。
5. 402 不是 429：402 表示預付費餘額用完，官方明確說不要重試，先充值。

一、先看清返回的是哪種 429

Gemini API 現在有兩套接口，錯誤的寫法不一樣：

新版 Interactions API：響應體裏是 error.code（小寫加下劃線的字符串）和 error.message。

json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "……"
  }
}

官方錯誤表裏，429 對應三個錯誤碼：

流式請求（stream: true）出錯時不走 HTTP 狀態碼，而是在事件流裏發一個 event_type 為 error 的事件，裏面同樣有 code 和 message。

舊版 generateContent API：響應體是 gRPC 風格，code 是數字狀態碼，status 是大寫的狀態名。

json
{
  "error": {
    "code": 429,
    "message": "……",
    "status": "RESOURCE_EXHAUSTED"
  }
}

官方對這一條的解釋是：你超過了 API 的某一項速率限制（RPM、TPM、RPD、支出等）——請求發得太多、用的 token 太多，或者超過了帳號檔位對應的支出類限制。

二、按原因逐項排查

1. 看自己的限額和用量。打開 AI Studio 的 Rate Limit 頁面（aistudio.google.com/rate-limit），每個模型的 RPM、TPM、RPD 上限和近期峰值都在上面。三項是分別檢查的，官方舉例：RPM 上限 20 時，一分鐘內第 21 個請求就會報錯，即使 TPM 還很富餘。
2. 確認是不是每天的配額用完了。RPD 在太平洋時間午夜重置，在那之前重試沒有意義。
3. 檢查是不是別的程序在用同一個項目。限額是項目級的，同項目下所有密鑰、所有程序共用。
4. 看用的是不是預覽版或實驗版模型。官方說明這類模型的限額更嚴。
5. 免費層撞限額很正常。免費層的限額本來就低，各模型具體數字以 Rate Limit 頁面為準。開通結算進入 Tier 1 後限額會提高，見本站《Gemini API 免費額度是多少：免費層級、RPM / TPM / RPD 速率限制與限額查詢》。
6. 付費層突然 429，想想是不是花得太快。官方對付費檔位設有「支出速率上限」，在滾動的 10 分鐘窗口內計算，超了同樣返回 429 RESOURCE_EXHAUSTED。官方給的辦法是：稍等再試；降低高成本請求的頻率，比如縮小上下文、縮短輸出；正常使用也經常撞到的話，申請提高限額。
7. 減少 token 用量。TPM 按輸入 token 計。刪掉重複的上下文，長對話只保留必要的歷史。
8. 失敗的請求也佔配額。官方帳單頁寫明，返回 400 或 500 的請求不收費，但仍計入配額。無間隔地連續重發只會更糟。
9. 不急的任務改用 Batch API。官方說明批量請求有獨立的速率限制，和普通調用分開計算（目前只有舊版 generateContent 支持 Batch）。
10. 還是不夠就申請提額。官方 Rate limits 頁面底部有付費層的提額申請表單，不保證批准。

三、怎麼重試才對

官方排錯頁的重試建議：

• 指數退避：第一次重試前等一小段時間（例如 1 秒），之後按 2 秒、4 秒、8 秒遞增；
• 加抖動（jitter）：在等待時間上加一點隨機量，避免所有客戶端同時重試；
• 只重試暫時性錯誤：429、408 和 5xx 可以重試；400、402、403 這類客戶端錯誤不要重試，它們說明密鑰無效、預付餘額耗盡或請求寫錯了；
• 設最大重試次數，防止死循環。

官方 SDK 已經內置了這套邏輯：排錯頁說明 Python SDK 預設會對超時、網絡問題、429 和 5xx 自動重試最多 4 次，初始等待約 1 秒，最長 60 秒。所以用 SDK 時通常不用自己再包一層；如果自己再寫重試，注意總請求次數會相乘。

直接調 REST 接口時，可以參考下面的寫法（示例用 httpx，安裝 google-genai 時會一併裝上）：

python
import os
import random
import time

import httpx

URL = "https://generativelanguage.googleapis.com/v1beta/interactions"
HEADERS = {
    "x-goog-api-key": os.environ["GEMINI_API_KEY"],
    "Content-Type": "application/json",
}
RETRYABLE = {408, 429, 500, 502, 503, 504}   # 官方：只重試暫時性錯誤


def create_with_backoff(payload, max_attempts=5, base_delay=1.0, max_delay=60.0):
    for attempt in range(1, max_attempts + 1):
        resp = httpx.post(URL, headers=HEADERS, json=payload, timeout=120)
        if resp.status_code == 200:
            return resp.json()

        try:
            err = resp.json().get("error", {})
        except ValueError:
            err = {}
        code = err.get("code")

        give_up = (
            resp.status_code not in RETRYABLE   # 400 / 402 / 403 等：重試沒用
            or code == "quota_exceeded"          # 每日配額用完：等重置或提額
            or attempt == max_attempts
        )
        if give_up:
            raise RuntimeError(f"{resp.status_code} {code}: {err.get('message')}")

        delay = min(max_delay, base_delay * 2 ** (attempt - 1))
        time.sleep(delay + random.uniform(0, 1))   # 加隨機抖動


result = create_with_backoff({
    "model": "gemini-3.8-flash",
    "input": "用一句話介紹你自己",
})
print(result["steps"][-1]["content"][0]["text"])

四、其他常見錯誤碼對照表

下表合併了官方兩版錯誤表。左邊是舊版 generateContent 的狀態名，右邊是新版 Interactions API 的錯誤碼。

幾條補充：

• 狀態頁：官方的 Gemini API 狀態頁在 aistudio.google.com/status。500、503 持續出現時先看這裏有沒有故障公告；仍無法解決，官方建議用 AI Studio 裏的「發送反饋（Send feedback）」按鈕上報。
• 400 的兩個新原因：從 Gemini 3.6 Flash、3.5 Flash-Lite 起，請求以模型角色的內容結尾（即「預填回覆開頭」）會返回 400；temperature、top_p、top_k 目前被忽略，官方預告未來的模型代際裏再傳也會返回 400。
• 密鑰無效的狀態碼兩套接口不同：新版錯誤表裏是 401 authentication；舊版 generateContent 的官方示例裏，無效密鑰返回的是 400 INVALID_ARGUMENT，提示「API key not valid. Please pass a valid API key.」。
• 密鑰被封：報「Your API key was reported as leaked. Please use another API key.」說明這把密鑰被檢測到泄露並封禁，需要新建密鑰，見本站《Gemini API Key 怎麼獲取：在 AI Studio 創建密鑰、設定環境變量與安全限制》。
• 403 Access Restricted（AI Studio 網頁裏）：官方排錯頁說明這表示使用方式不符合服務條款，常見原因之一是所在地區不在可用地區列表內。請遵守所在地法律和服務條款。
• 內容被攔截不是 HTTP 錯誤：因安全、引用（recitation）等原因被攔時，Interactions API 會給出 safety、recitation、prohibited_content 這類「生成被阻止」代碼，需要修改輸入後再試。

常見問題

Q：我才發了幾個請求就 429？

先確認是哪一項超了。免費層的限額本來就低（具體數字看 Rate Limit 頁面），循環裏連發請求很容易觸發每分鐘的限制；另外看項目下是否還有別的程序在跑，以及用的是不是限額更嚴的預覽版模型。

Q：餘額充足為什麼還是 429？

速率限制和餘額是兩回事。付費層還有按 10 分鐘計的支出速率上限，以及檔位對應的每月帳單上限，詳見本站《Gemini API 怎麼收費：按 token 計費、預付費充值（Prepay）與支出上限設定》。

Q：換一把密鑰行不行？

同一個項目下的密鑰共用限額，換了也沒用。

Q：開通付費後多久生效？

官方說明從免費層到 Tier 1 通常立即生效，之後的升檔一般在 10 分鐘內。

Q：延遲很高、token 用得特別多，是出錯了嗎？

通常不是。官方排錯頁解釋，Gemini 3 系列預設開啟思考，會產生額外的推理 token 並拉長響應時間。對速度或成本敏感時，把思考等級調低。

參考資料

• API errors（Interactions API 版，官方）：https://ai.google.dev/gemini-api/docs/api-errors
• API errors（generateContent 版，官方）：https://ai.google.dev/gemini-api/docs/generate-content/api-errors
• Troubleshooting guide（官方）：https://ai.google.dev/gemini-api/docs/troubleshooting
• Rate limits（官方）：https://ai.google.dev/gemini-api/docs/rate-limits
• Billing（官方）：https://ai.google.dev/gemini-api/docs/billing
• Troubleshoot Google AI Studio（官方）：https://ai.google.dev/gemini-api/docs/troubleshoot-ai-studio
• Available regions for Google AI Studio and Gemini API（官方）：https://ai.google.dev/gemini-api/docs/available-regions
• What's new in Gemini 3.6 Flash and 3.5 Flash-Lite（官方）：https://ai.google.dev/gemini-api/docs/whats-new-gemini-3.6