Google 日曆 API 設有配額，確保所有使用者都能公平使用。使用 Calendar API 時，請留意以下三項重要限制：
API 使用配額：系統會針對每個專案和每位使用者強制執行配額。詳情請參閱「Calendar API 使用配額類型」一文。
Google 日曆一般使用限制：Google 日曆 API 是共用服務，因此設有限制，以保護 Google Workspace 系統的整體效能。詳情請參閱「避免達到日曆使用上限」。
作業限制：這些限制隨時可能有所變動。舉例來說，如果您嘗試快速連續寫入單一日曆。
Calendar API 配額
系統會強制執行兩種配額：
每項專案每分鐘：這是指 Google Cloud 專案在一分鐘內可發出的要求數量。
每位使用者每項專案每分鐘：這是指任何一位特定使用者可在您的雲端專案中發出的要求數量。這項限制旨在協助您確保使用者能公平分配用量。
配額是根據滑動區間，以每分鐘為單位計算。如果流量在某分鐘內快速爆增，超過每分鐘配額，系統會在下一個時間範圍內限制速率，確保平均用量維持在配額內。
下表詳細列出這些限制：
| 用量限制類型 | 限制 |
|---|---|
| 每項專案每分鐘 | 10,000 項要求 |
| 每位使用者每項專案每分鐘 | 600 項要求 |
每日結算最低曝光次數門檻
這項專案每日限制定義了 Google Cloud 專案在 24 小時內可使用的要求數量上限，超過上限就會開始收費。
如果用量低於這個門檻，就不會產生額外費用，Google Cloud 帳戶也不會收到帳單。我們會在 2026 年稍晚提供完整的帳單詳細資料，並在任何異動生效前至少 90 天發送通知。
您無法要求提高這項每日門檻限制。
下表詳細說明限制：
| 門檻限制類型 | 限制 |
|---|---|
| 每個專案每天 | 1,000,000 個要求 |
詳情請參閱「Google Workspace standardized model for agent tools and APIs」。
解決時間配額錯誤
對於所有時間相關錯誤 (每 X 分鐘最多 N 個要求)，建議您的程式碼擷取例外狀況，並使用截斷指數輪詢，確保裝置不會產生過多負載。
指數輪詢是網路應用程式的標準錯誤處理策略。指數輪詢演算法會以指數方式重試要求，並將每次要求之間的等待時間逐漸增加至最大輪詢時間，如果要求仍未成功，請務必隨著時間增加要求之間的延遲時間，直到要求成功為止。
演算法範例
指數輪詢演算法會以指數方式重試要求，並將每次重試之間的等待時間逐漸增加至最大輪詢時間，例如：
- 對 Google 日曆 API 提出要求。
- 如果要求失敗，請等待 1 +
random_number_milliseconds秒後再重試要求。 - 如果要求失敗，請等待 2 +
random_number_milliseconds秒後再重試要求。 - 如果要求失敗，請等待 4 +
random_number_milliseconds秒後再重試要求。 - 依此類推，時間上限為
maximum_backoff。 - 繼續等待和重試，直到重試次數達特定上限，但不再增加每次重試之間的等待時間。
其中：
- 等待時間為
min(((2^n)+random_number_milliseconds), maximum_backoff)，n會在每次疊代 (要求) 時增加 1。 random_number_milliseconds是小於或等於 1,000 的隨機毫秒數。這種設定有助於避免多個用戶端在特定情況下全部同步進行處理並同時重試，導致同步傳送每一波要求。random_number_milliseconds的值會在每次重試要求後重新計算。maximum_backoff通常是 32 或 64 秒，適合的值視用途而異。
用戶端達到 maximum_backoff 時間上限後，還是可以繼續重試，但接下來的重試工作就不需繼續增加輪詢時間。舉例來說，如果用戶端使用的 maximum_backoff 時間上限是 64 秒，達到這個值之後，用戶端就可以維持在每 64 秒重試一次的頻率。到了特定時間點後，用戶端應停止無限重試。
重試之間的等待時間和重試次數，應視用途及您的網路狀況而定。
定價
Google 日曆 API 的所有標準用途都不會產生額外費用。預計在 2026 年稍晚，超出配額要求限制將會產生費用，並計入您的 Google Cloud 帳單帳戶。詳情請參閱「Google Workspace standardized model for agent tools and APIs」。
申請提高配額
您可以依據專案的資源用量，要求調整配額。服務帳戶發出的 API 呼叫會視為使用單一帳戶。我們不保證一定能核准您提出的配額調整要求。如果配額調整要求會大幅提高配額值，可能需要較長時間才能通過核准。
並非所有專案的配額都相同。隨著您使用 Google Cloud 的時間越長，可能需要提高配額值。如果預期用量將大幅攀升，可以透過 Google Cloud 控制台的「配額與系統限制」頁面，主動要求調整配額。
如要進一步瞭解相關內容，請參閱下列資源：
疑難排解
如果超過任一配額，系統就會限制速率，並在查詢的回應中傳回 403
usageLimits 或 429
usageLimits 狀態碼。
如果發生這種情況，請嘗試下列做法：
如果專案規模擴大，使用者人數增加，可以申請提高配額。
如果達到個別使用者的配額上限，可以採取以下做法：
如果您使用服務帳戶，請將負載分配給使用者，或在多個服務帳戶之間分配負載。
雖然您可以要求提高每位使用者的配額，但一般來說，不建議將配額提高至高於預設值，因為您的應用程式可能會開始達到其他類型的限制，例如一般日曆用量限制或作業限制。
如要測試配額限制，請註冊僅供測試的專案，並採用與正式版專案類似的設定。詳情請參閱「測試配額限制處理方式」。
隨機產生流量模式
多個用戶端同時執行作業時，日曆用戶端容易出現流量尖峰模式。舉例來說，日曆用戶端常見的不良做法是在午夜執行完整同步。這幾乎肯定會導致每分鐘配額超出上限，進而造成頻率限制和輪詢。
為避免這種情況，請盡可能將流量分散到一天中的不同時段。如果客戶需要每天同步，請客戶決定隨機時間 (每位客戶的時間都不同)。如需定期執行作業，請將間隔時間調整 +/- 25%。這樣一來，流量分配會更平均，使用者體驗也會大幅提升。
使用推播通知
常見的用途是，每當使用者日曆中的內容有變更時，就執行某項動作。這裡的反模式是重複輪詢每個感興趣的日曆。這樣很快就會用盡所有配額。舉例來說，如果您的應用程式有 5,000 名使用者，且每分鐘輪詢每位使用者的日曆一次，即使尚未完成任何工作，每分鐘也至少需要 5,000 個配額。
伺服器端應用程式可以註冊推播通知，讓我們在發生您感興趣的事件時通知您。雖然設定這些項目需要更多時間，但可大幅提升配額使用效率，並提供更優質的使用者體驗。請務必指定要接收通知的 eventType。詳情請參閱「推播通知」。
使用服務帳戶適當分配
如果應用程式使用全網域委派發出要求，根據預設，系統會針對「每個專案每位使用者每分鐘」配額向服務帳戶收費，而非您模擬的使用者。也就是說，即使服務帳戶可能在多位使用者的日曆上運作，配額仍可能用盡，並受到速率限制。
如要避免這種情況，請使用 quotaUser 網址參數 (或 x-goog-quota-user HTTP 標頭) 指出要向哪位使用者收費。這項資訊僅用於計算配額。詳情請參閱「限制每位使用者的要求數」。
測試配額限制處理方式
為確保應用程式能妥善處理達到配額上限的情況 (例如透過指數輪詢重試)，並盡量減少對使用者造成的潛在干擾，強烈建議您在實際環境中測試情境。
如要測試，但不想干擾實際應用程式的使用情形，建議您在 Google Cloud 控制台中註冊僅供測試的專案，然後設定 OAuth 同意畫面，方式與生產環境專案類似。接著，您可以為這個專案設定人為的低配額限制，並觀察應用程式的行為。