Gemini API 呼叫逾時，先分清是哪一種失敗

Gemini API 呼叫逾時，不一定代表服務端沒有回應。錯誤可能發生在 DNS 查詢、建立 TCP 或 TLS 連線、等待模型回應，或接收串流資料的過程；如果只看到程式最後報出「timeout」，就立刻換線或提高逾時上限，可能會掩蓋真正原因。

先記下發生時間、使用的 SDK 或 HTTP 用戶端、請求是否啟用串流，以及錯誤類型和狀態碼。若請求根本沒有收到 HTTP 回應，優先檢查本機網路、DNS、代理和 TLS；若收到 4xx 或 429，則應先看請求內容、認證與配額；若連線成功但等候很久，才進一步檢查模型處理時間、輸入大小和讀取逾時。這些線索可以幫助區分網路層問題與 API 層問題。

  • ✅ 記錄錯誤原文、狀態碼、SDK 版本與請求是否為串流。
  • ✅ 使用同一份程式碼和相同請求，比較不同網路環境的結果。
  • ❌ 不要把 API 金鑰、完整授權標頭或含敏感資料的請求貼到公開討論區。

排查順序：先確認錯誤發生在哪個階段，再依序檢查 DNS、代理、逾時設定和配額；一次只改一項，才能看出調整是否有效。

先檢查 DNS、網路與 TLS 連線

DNS 解析失敗時，程式可能出現找不到主機、名稱解析錯誤或連線逾時。可以先確認執行程式的機器是否能正常解析 API 主機名稱，再檢查本機 DNS 設定、公司網路的 DNS 政策，以及是否有安全軟體或網路設備攔截查詢。瀏覽器能開啟一般網站，不代表執行環境使用相同的 DNS、代理設定或網路路徑；容器、遠端主機和本機終端也可能各自有不同設定。

如果 DNS 能解析，但連線仍卡在建立階段，請確認目前網路是否允許程式連到目標服務，以及防火牆或公司網路政策是否限制相關流量。TLS 憑證錯誤則要另外處理：檢查系統時間、憑證存放區、公司代理是否進行 TLS 檢查，以及執行環境使用的憑證設定。不要用停用憑證驗證的方式「修復」問題，這會降低連線安全性，也無法定位根因。

測試時應在實際執行程式的環境進行。例如程式跑在容器中，就要在容器內檢查 DNS 與連線；在開發電腦成功，不等於部署環境也有相同結果。比較不同環境時，保留相同的請求內容和程式設定，並避免同時更換 DNS、代理與 SDK 版本。

若錯誤包含名稱解析、連線建立或憑證相關字樣，先不要反覆重試模型請求。重試無法修復 DNS 或 TLS 設定，還可能增加不必要的請求量。

檢查代理環境變數與流量路徑

命令列工具、SDK 和 HTTP 用戶端可能讀取系統代理，也可能讀取環境變數；不同語言與套件對大小寫、優先順序和例外清單的處理方式並不完全相同。常見環境變數包括 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY，部分環境也會設定小寫版本。請檢查執行程式的程序實際繼承了哪些值，不要只看桌面代理軟體顯示為已連線。

若代理位址錯誤、代理本身無法連線，或 NO_PROXY 意外排除了目標主機，程式可能直接逾時或走到與預期不同的出口。可以在安全的測試環境中暫時移除相關變數後比較結果，但若工作環境要求經由覈准代理連線，就應遵循組織政策，不要擅自繞過網路管制。檢查記錄時也要遮蔽代理帳密與完整代理網址。

若使用 VPN 或代理工具，請確認目標應用程式的流量確實由預期路徑傳送。系統代理模式通常隻影響會遵循系統設定的程式；採用自有網路堆疊的 SDK、容器或背景服務，未必會使用相同代理。測試出口或切換線路時，保持 DNS、程式設定和請求內容不變，才能判斷是否是路徑差異造成問題。需要了解不同網路環境下的連線選擇時，可參考 VPNSR 中國出差VPN，並依所在地法規、機構政策及服務條款使用網路工具。

使用者端顯示連線成功，也不能證明 API 請求已通過代理；反過來，API 呼叫逾時也不必然代表出口 IP 有問題。請同時檢查程式的代理設定、連線錯誤與請求結果。若工作環境需要固定出口或依政策管理出口 IP，應先確認服務端、代理端與組織網路各自的要求，避免在短時間內頻繁切換出口，造成驗證或存取狀態改變。

合理設定連線、讀取逾時與重試

逾時通常需要分開理解。連線逾時限制建立連線需要等待多久；讀取逾時限制連線建立後，等待回應資料的時間；整體逾時則可能限制整個請求流程。若把這些設定混為一談，單純提高一個數值未必能處理真正卡住的階段。請查看目前 SDK 或 HTTP 用戶端的文件，確認設定名稱、單位和預設行為；不同版本可能有所差異。

模型回應時間會受請求內容、模型處理狀況、網路路徑及是否使用串流等因素影響。讀取逾時若設得過短，可能在服務仍正常處理時就中止等待；設得過長，則會讓程式在連線已失效時佔用資源。建議依應用程式的使用情境設定合理上限，並在監控或日誌中分別記錄連線階段和等待回應階段，而不是盲目設定極大的逾時值。

重試應有條件且有上限。網路暫時中斷、服務端暫時性錯誤，或配額服務回傳可重試的狀態時，可以依 SDK 支援情況採用逐步增加等待時間的策略，並遵循回應提供的重試資訊。認證失敗、請求格式錯誤或參數不合法，通常不會因重送而改善；對這類錯誤應修正原因後再送出。對會產生費用或執行非冪等操作的請求，也要先確認重試不會造成重複處理。

若啟用串流，程式可能已收到部分內容，之後才因讀取逾時中斷。此時要分辨是串流長時間沒有新資料、程式未持續讀取回應，還是網路連線確實中止。不要把「等待完整回應」的計時器直接套用到串流讀取流程；應依用戶端支援方式處理資料片段、取消請求與錯誤狀態。

確認配額、認證與請求內容

收到 HTTP 回應時，先看狀態碼與錯誤本文，不要一律歸類為網路逾時。429 通常提示請求速率或可用配額受到限制，但實際原因要以 API 回應與專案設定為準；401 或 403 類錯誤應檢查金鑰、權限、專案與服務設定；其他 4xx 往往需要修正請求參數、模型名稱或內容格式。不要把金鑰放在前端程式、公開儲存庫或日誌中，也不要將完整授權標頭傳給第三方診斷網站。

檢查請求是否包含過大的輸入、過多上下文或不必要的附件。為了定位問題，可先用不含敏感內容的最小請求測試，再逐步恢復原本的提示詞與資料。若最小請求成功而完整請求失敗，應檢查輸入大小、內容格式、附件讀取方式和程式是否正確等待回應；若兩者都無法連線，再回到 DNS、代理及 TLS 層排查。

API 與 Gemini 網頁版不是同一條請求路徑。網頁版使用瀏覽器、登入狀態和產品自身的服務流程；API 則由程式透過 SDK 或 HTTP 用戶端連線，並使用 API 金鑰、專案設定、配額與程式端的代理及逾時配置。因此網頁版可以使用，不代表 API 金鑰、程式網路路徑或專案配額一定正常；API 成功也不代表網頁版登入狀態沒有問題。兩者應分開檢查，避免用其中一方的結果直接判定另一方。

判斷重點：有明確狀態碼時，優先處理認證、請求或配額；沒有 HTTP 回應時，先從 DNS、代理、TLS 和連線階段著手。

建立可重現的排查紀錄

有效的排查紀錄不需要包含機密內容。請保留錯誤類型、時間、程式與 SDK 版本、使用的模型設定、是否串流、逾時配置、HTTP 狀態碼，以及請求是否在 DNS、連線、等待回應或讀取資料時失敗。請遮蔽 API 金鑰、使用者資料、提示詞中的敏感資訊和代理憑證；若回應含有請求識別資訊，可依官方支援流程提供，而非公開張貼。

  1. 先測試原始環境。記錄原本的錯誤與設定，不要先同時更新套件、改 DNS 和切換出口。
  2. 使用最小請求比較。在符合服務政策的前提下，移除不必要內容，確認基本認證和連線是否可用。
  3. 逐項檢查網路設定。在執行程式的環境確認 DNS、代理環境變數、TLS 憑證與防火牆政策。
  4. 核對回應與配額。查看狀態碼、錯誤本文、專案權限及配額資訊，再決定是否需要調整請求或等待。
  5. 最後調整逾時與重試。依實際失敗階段設定逾時，並只對適合重試的錯誤採取有上限的重送策略。

如果問題只在特定網路出現，請比較該網路的 DNS、代理要求和路由政策；若只在特定執行環境出現，則比較容器、伺服器或本機程序所繼承的設定。若已確認錯誤來自配額或服務端，持續更換 DNS 和 VPN 線路不會增加可用配額，也不應以高頻率重試掩蓋問題。提供精簡、去識別化且可重現的紀錄，通常比單純描述「一直逾時」更有助於進一步診斷。

  • ✅ 一次只調整一項設定，並記錄調整前後的錯誤差異。
  • ✅ API 與網頁版分開驗證，不以一方的成功推定另一方正常。
  • ❌ 不要停用 TLS 驗證、公開 API 金鑰，或無限制重試請求。