註冊
GeminiGemini

Gemini API 報錯 400、403、429、500、503、504 怎麼辦：官方錯誤碼對照，502 和 error 13 官方沒列出時怎麼查

Gemini API 報錯 400、403、429、500、503、504，哪些該重試，哪些要先改請求或補帳單？按官方錯誤頁和排查頁（2026-10-30 查詢）逐項對照。官方沒有列出 502 和 error 13，本文說明遇到這兩種時能做什麼。

NNathaniel bigo··原創首發·AI 輔助撰寫
9 分鐘讀完
資料核對於 2026-10-30 · 依據官方文檔與公開資料整理 免費帳號 帳號
本文根據 Gemini API 官方文檔的「API errors」頁和「Troubleshooting」頁整理，資料核對於 2026-10-30。官方兩頁都沒有出現 502，也沒有出現「error 13」，這兩種在下面單列一節說明。配圖為本站整理的示意圖，不是網頁截圖。

適用於誰

  • 調用 Gemini API，返回 HTTP 400、403、429、500、503、504 的開發者；
  • 在 Cursor、Cline、Cherry Studio 等工具裏填了 Gemini API Key，看到報錯的人；
  • 搜「Gemini 報錯 502」「Gemini error 13」的人。

結論先說

  1. 官方錯誤頁把錯誤分成三類：請求本身的問題（400、401、402、403、404、416 等，改請求或查帳號，重試沒用）、限流類（429，等一等再試）、服務端類（500、503、504）。
  2. 429 有三種代碼：rate_limit_exceeded（每分鐘或每秒的請求或 token 超限）、quota_exceeded（日配額用完）、too_many_requests（短時間請求太多）。前者和後者等待後按指數退避重試，日配額則要等重置或申請提高。429 的詳細講解見 /guides/gemini-api-429-resource-exhausted。
  3. 500 api_error：服務端意外錯誤，重試，持續就聯絡支持。503 service_unavailable：服務暫時過載或不可用，等待後按指數退避重試。504 deadline_exceeded：請求沒在時限內完成，官方建議去掉或調大客戶端的超時設定，讓服務端用預設值。
  4. 官方推薦的重試方式：指數退避，加隨機抖動，設定最大重試次數；官方說明 Python SDK 預設對暫時性錯誤最多重試四次。
  5. 502 和 error 13 官方頁面裏沒有。先看官方狀態頁，確認不是官方故障，再按通用做法處理，見第三節。

Gemini API 常見錯誤碼速查

圖：本站根據 Gemini API 錯誤頁 整理的示意圖

一、請求類錯誤：重試沒有用

代碼HTTP含義怎麼辦
invalid_request400請求格式不對或參數無效對照 API 參考檢查語法和參數
failed_precondition400前提條件不滿足，例如帳單未開通檢查帳單狀態和帳號前提
parameter_unknown400請求裏有不認識的參數刪掉該參數再試
authentication401API Key 缺失、無效或過期檢查 Key
payment_required402預付費餘額用完補充餘額或開啟自動充值，補充前不要重試
permission_denied403Key 沒有權限，或項目被限制檢查權限、所在層級和帳單
not_found / model_not_found404資源或模型不存在檢查路徑、參數和模型名
out_of_range416參數超出有效範圍檢查取值和限制

排查頁對 403 的幾種情形寫得更細：

  • 項目被拒絕訪問，或項目狀態是 Restricted、Free tier unavailable、Payment needed、Unavailable；
  • 免費層不可用：關聯一個有效的 Cloud Billing 帳號；
  • 需要付款：處理欠費，或在帳單頁更新付款方式；
  • Key 泄露或被封：官方會提示「API key was reported as leaked」，要在 AI Studio 裏新建一個 Key。

Key 的創建和保管，可參考 /guides/gemini-api-python-quickstart。免費層和付費層的額度區別，見 /guides/gemini-api-free-tier-rate-limits 和 /guides/gemini-api-price-official。

二、限流和服務端錯誤：可以重試

代碼HTTP含義怎麼辦
rate_limit_exceeded429每分鐘或每秒的請求或 token 超限等待後按指數退避重試
quota_exceeded429日配額用完等配額重置，或申請提高
too_many_requests429短時間內請求太多等待後按指數退避重試
api_error500服務端意外錯誤重試，持續就聯絡支持
service_unavailable503服務暫時過載或宕機等待後按指數退避重試
deadline_exceeded504請求在時限內沒完成去掉或調大客戶端超時
unimplemented501該功能或操作不支持檢查 API 能力，換支持的功能
cancelled499客戶端在完成前取消了請求通常是客戶端斷開，無需處理

另外官方頁面還列了內容被攔截的代碼（如 safety、prohibited_content、image_safety 等），官方說法是修改輸入後再試；以及生成錯誤（如 malformed_function_call、no_image）。這些和網絡、額度無關，是請求內容或模型輸出方面的問題。

三、502 和 error 13：官方沒寫，怎麼辦

官方的 API 錯誤頁使用 api_error、service_unavailable、deadline_exceeded 這樣的小寫名稱，頁面裏沒有502，也沒有「error 13」。網上常見的 500 INTERNAL、UNAVAILABLE 這類大寫名稱，也沒有出現在這一頁裏。所以這兩種報錯沒有官方的逐條解釋，建議這樣查：

Gemini API 報錯先這樣查

圖：本站根據 Gemini API 排查頁 整理的示意圖

  1. 看官方狀態頁 aistudio.google.com/status，確認是不是官方在處理事件；
  2. 502 在 HTTP 裏通常表示網關或中間代理收到了上游的無效響應，所以在你和 Google 之間還有代理、網關或第三方中轉的話，先繞開它直接請求官方地址試試；
  3. 把它當作暫時性錯誤處理：指數退避重試，設定最大次數；
  4. 用的是第三方工具或客戶端時，換一個客戶端或更新版本再試，並查看工具自己的日誌；
  5. 持續出現，儲存請求 ID 等資訊，向官方反饋。

常見問題

Q：Gemini 網頁或 App 裏的報錯呢？

那是另一類，見 /guides/gemini-error-messages-table 和 /guides/gemini-down-check-status-page。

Q：429 是不是一定是我用多了？

官方把 429 分成三種代碼，只有看到 quota_exceeded 才是日配額用完，其他兩種是短時間內太快，等一等就好。

Q：需要 Google 帳號怎麼辦？

本站有 Google 帳號相關服務，具體以頁面說明為準。

參考資料

  • Gemini API 錯誤 — https://ai.google.dev/gemini-api/docs/api-errors
  • Gemini API 排查 — https://ai.google.dev/gemini-api/docs/troubleshooting
  • Google AI Studio 狀態頁 — https://aistudio.google.com/status

Nathaniel 的更多內容

  1. 01

    Microsoft Copilot 官網入口在哪、怎麼下載：網頁版、Windows 應用、手機應用和工作帳號入口怎麼選

    Microsoft Copilot 有網頁版、Windows 應用、手機應用，工作或學校帳號還有單獨入口。本文按微軟支持頁面講清各入口、各自支持的登入帳號、Windows 應用從 Microsoft Store 下載，以及怎麼區分微軟的 Copilot 和 GitHub Copilot。

    其他 AI 工具0
  2. 02

    GitHub Copilot 提示無法連接到服務怎麼辦：could not connect to server、ETIMEDOUT、證書錯誤的官方排查辦法

    Copilot 提示 could not connect to server、read ETIMEDOUT 或證書錯誤，多與代理、防火牆有關。本文按 GitHub 官方網絡錯誤排查文檔，講 curl 測連通性、代理與認證限制、證書錯誤處理和公司網絡放行清單。

    GitHub Copilot0
  3. 03

    GitHub Copilot 報錯「Language model unavailable」怎麼辦：VS Code 團隊說的頭號原因，以及怎麼收集診斷資訊

    VS Code 裏 Copilot Chat 提示 Language model unavailable，官方沒有單獨說明。本文按 VS Code 團隊的說法講頭號原因（公司防火牆沒放行新端點）、怎麼看 Failed to fetch models、運行 Chat Diagnostics。

    GitHub Copilot0
  4. 04

    Windows 裏的 Copilot 是什麼軟件、能卸載嗎、怎麼關閉：卸載路徑、Copilot 鍵和 Win+C 的處理，公司電腦怎麼管

    Windows 11 新電腦上的 Copilot 是微軟的 AI 助手應用，可以卸載。本文按微軟官方文檔講清它是什麼、卸載路徑、不想被 Copilot 鍵或 Win+C 喚起怎麼改、卸載後怎麼裝回來，以及公司電腦上 IT 管理員的 AppLocker 和 PowerShell 做法。

    其他 AI 工具0
  5. 05

    Cursor 報錯「User is unauthorized」怎麼辦：官方員工給的排查順序，以及怎麼取到 Request ID 反饋

    Cursor 裏發消息時提示 User is unauthorized，官方幫助中心沒有單獨說明。本文整理官方論壇裏員工的回覆：先檢查有沒有自定義 Base URL、退出重新登入並完全重啟，仍不行就用 Report AI Action 取新的 Request ID 反饋；電郵域名被攔截的情況官方怎麼說。

    Cursor0
  6. 06

    Cursor 登入提示「Can't verify the user is human」怎麼辦：人機驗證失敗的常見原因，以及登入域名遷移後的放行清單

    Cursor 登入時提示無法驗證用戶為真人，官方幫助中心沒有這條報錯的專門說明。本文整理官方論壇裏反饋的常見情形（攔截人機驗證請求、密碼管理器自動點繼續、換瀏覽器），並按官方幫助頁說明 Cursor 登入頁正遷移到 accounts.spacex.ai 與 accounts.x.ai，公司網絡需要放行。

    Cursor0

同模型

  1. 01

    Nano Banana 官網入口在哪、免費能用嗎：Google 官方入口、Nano Banana 2 與 2.1 的免費和付費區別

    Nano Banana 官網地址是什麼、免費能用多少？Nano Banana 是 Google Gemini 的圖像模型，官方入口是 gemini.google.com 和官方介紹頁。按官方頁面核對：免費版用 Nano Banana 2，2.1 需要 Google AI 套餐，API 沒有免費層。

    Gemini0
  2. 02

    Gemini 3.5 Pro 是什麼、發佈了嗎、怎麼用：官方說法梳理，以及現在 Gemini 裏該選哪個模型

    Gemini 3.5 Pro 發佈了嗎？按 Google 官方網誌、Gemini 更新記錄和 API 模型列表核對：截至 2026-10-19 官方沒有宣佈 3.5 Pro 已發佈，最新的是 Gemini 4 Argon。講清官方說過什麼，以及 Gemini 應用裏各套餐現在能選哪些模型。

    Gemini0
  3. 03

    Gemini 打不開、無法登入、無法使用怎麼辦：帳號類型、年齡、瀏覽器和官方兩條登入提示

    Gemini 怎麼打不開？無法登入、無法使用怎麼辦？按官方「Sign in to Gemini Apps」頁排查：帳號類型、年齡、支持的瀏覽器、國家和語言名單，以及「Can't access this service」「Something went wrong」兩條提示的官方解釋。

    Gemini0
  4. 04

    Gemini 無法生成圖片怎麼辦：入口、年齡與地區、提示詞、模型和額度逐項排查

    Gemini 無法生成圖片怎麼辦？按官方幫助中心逐項排查：有沒有登入、年齡和地區是否滿足、生圖入口在哪、提示詞怎麼寫才會出圖、Flash-Lite 的 Nano Banana 2 Lite 有什麼限制、圖片被移除和額度用完時怎麼辦。

    Gemini0
  5. 05

    Gemini 分享對話怎麼操作：生成公開連結、對方能看到什麼、怎麼刪除分享連結

    Gemini 的「分享對話」會生成一個任何人都能打開的公開連結。本文按官方幫助中心講清：分享步驟、連結裏包含哪些內容（整段對話、上載的圖片、Canvas 作品）、別人能做什麼、連結什麼時候會自動失效、怎麼查看和刪除自己所有的公開連結。

    Gemini0
  6. 06

    Gemini API Python 調用教學：安裝 google-genai SDK、流式輸出、多輪對話與傳圖片

    用官方 google-genai SDK 調 Gemini API：安裝配置、第一個請求、系統指令與思考等級、流式輸出、多輪對話、傳圖片和查看 token 用量，按 2026 年 10 月官方預設的 Interactions API 寫法。

    Gemini0

同產品的其他教學

  1. 01

    Gemini 無法下載 Excel 怎麼辦：官方支持導出的文件格式，怎麼讓它生成 .xlsx，導不出來的幾種辦法

    Gemini 能直接生成並導出 Excel 嗎？Google 官方網誌說，Gemini 可以在聊天裏生成 PDF、Word、Excel、Docs、Sheets、Slides 等文件，大多數格式能下載或發送到 Drive。官方沒有寫導出失敗的專門排查，本文給出讓它生成文件和導不出時的做法。

    Gemini0
  2. 02

    Gemini 提示「此帳號無法使用」（Can't access this service）怎麼辦：帳號類型、年齡、Family Link 與工作學校帳號的官方條件

    Gemini 提示 Can't access this service，意思是這個帳號目前不符合使用條件。官方寫明瞭可用的帳號類型、年齡要求和 Family Link 帳號不能用。本文按帳號類型對照，並給出 Something went wrong 的處理。

    Gemini0
  3. 03

    Gemini Pro 免費試用、學生優惠到期後怎麼辦：自動轉付費、重新驗證 SheerID、取消後會失去什麼

    Google AI Pro 學生優惠或試用到期後會怎樣？官方說會自動轉為正常付費的 Plus 或 Pro，會提前通知；沒有按時重新驗證 SheerID 會失去優惠。本文按官方幫助中心整理到期規則、取消後失去的內容和第三方訂閱的處理。

    Gemini0
  4. 04

    Gemini 怎麼切換模型：Flash-Lite、Flash、Pro、Argon 的選擇步驟、思考等級和自動選擇

    Gemini 網頁版怎麼手動切換模型？官方步驟是點聊天框底部當前模型再選，需要有 Google AI 方案，帶鎖圖標的要升級。本文按官方說明整理各方案可選模型、思考等級預設值和自動模型選擇。

    Gemini0
  5. 05

    Gemini App 閃退、打不開怎麼辦：安卓、Mac、Windows 的官方裝置要求、更新方法和工作資料限制

    Gemini App 閃退或打不開，先對照官方裝置要求：安卓需要 Android 9 以上和 2 GB 內存，Mac 需要 macOS 15 和 Apple 芯片，Windows 需要 Windows 10 以上。本文整理各端要求、更新方法和不能用的情形。

    Gemini0
  6. 06

    Gemini 語音對話（Live）用不了怎麼辦：網頁版為什麼沒有、攝像頭和螢幕共享自動關閉、鎖屏與權限的官方說明

    Gemini Live 找不到入口、攝像頭自己關了、共享螢幕失敗？官方幫助中心寫明 Live 目前不在網頁版提供，需要個人帳號或有權限的工作帳號，共享螢幕要開通知權限，鎖屏時不能啟動。本文逐項整理。

    Gemini0

0 條評論

登入 後參與評論

還沒有評論，來搶沙發～