Google 日曆 API 設有配額，確保所有使用者都能公平使用。使用 Calendar API 時，請注意以下三項重要限制：
API 使用配額：系統會針對每個專案和每位使用者強制執行配額。詳情請參閱「Calendar API 使用配額類型」一文。
一般日曆使用限制：Calendar API 是共用服務，因此設有限制，以保護 Google Workspace 系統的整體效能。詳情請參閱「避免達到 Google 日曆用量限制」。
作業限制：這些限制隨時可能套用。舉例來說，如果您嘗試快速連續寫入單一日曆，可能會受到限制。
Calendar API 配額
系統會強制執行兩種配額：
每項雲端專案每分鐘：這是指 Google Cloud 雲端專案在一分鐘內可發出的要求數量。
每位使用者每項專案每分鐘：這是指任何特定使用者可在您的雲端專案中發出的要求數量。這項限制有助於確保使用者能公平地分配用量。
配額是使用滑動視窗，以每分鐘為單位計算。如果流量突然暴增，超過每分鐘配額，系統會在下一個時間範圍內進行速率限制，確保平均用量維持在配額內。
下表詳細列出這些限制：
| 用量限制類型 | 限制 |
|---|---|
| 每項專案每分鐘 | 10,000 項要求 |
| 每位使用者每項專案每分鐘 | 600 項要求 |
每日結算最低曝光次數門檻
這個專案每日限制定義了 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 只會使用這個參數計算配額。詳情請參閱「限制每位使用者的要求數」。
測試配額限制處理方式
為確保應用程式能妥善處理達到配額上限的情況 (例如透過指數輪詢重試)，並盡量減少對使用者造成的干擾，請在實際環境中測試應用程式。
如要測試，但不想干擾實際應用程式的使用情形，請在 Google Cloud 控制台中註冊獨立的測試專用專案，然後設定 OAuth 同意畫面，方式與生產環境專案類似。接著，您可以為這個專案設定人為的低配額限制，並觀察應用程式的行為。
Calendar MCP 伺服器配額
日曆 MCP 伺服器會使用查詢費用分配指標。下表詳細列出各個 Calendar MCP 伺服器方法的查詢費用 (依節區分)：
日曆 MCP 配額
系統會強制執行兩種配額：
每分鐘每項雲端專案：這是您的 Cloud 專案一分鐘的查詢費用。
每位使用者每項專案每分鐘：這是雲端專案中任何單一使用者在一分鐘內可能產生的查詢費用。
下表詳細列出這些配額：
| 用量限制類型 | 查詢費用 |
|---|---|
| 每項專案每分鐘 | 10,000 |
| 每位使用者每項專案每分鐘 | 600 |
Calendar MCP 工具組配額
下表詳細列出各個 calendarmcp.googleapis.com 工具集的查詢費用：
| 端點 | 工具 | 查詢費用 |
|---|---|---|
/mcp/v1 |
|
1 |
|
10 |
|
|
1 |
|
|
1 |
|
|
1 |
|
|
1 |
|
|
1 |
|
|
1 |
|
|
1 |
詳情請參閱日曆 MCP API 參考資料。