設定限制和配額可以保護 Google 基礎架構，使其無法自動化處理程序以不當方式使用 Directory API。API 發出太多要求時，有可能是無害的錯字，或是因為缺乏效率的系統而做出不需要的 API 呼叫。無論原因為何，只要特定來源的流量達到特定等級，Google Workspace 系統的整體健康狀態就會必須封鎖來自特定來源的流量。確保某位開發人員的行為不會對更廣大的社群造成負面影響。
萬一 API 要求失敗，API 就會傳回 HTTP 狀態碼和錯誤原因。此外，回應主體會詳細說明導致錯誤的原因。
以下清單列出因達到配額限製而造成的錯誤可能出現的錯誤代碼、原因、對應說明，以及建議採取的行動。
| 程式碼 | 原因 | 說明 | 建議做法 |
|---|---|---|---|
| 403 | userRateLimitExceeded | 表示已超過使用者頻率限制。在 Google Cloud 控制台中，預設值是每項 Google Cloud 專案每位使用者每分鐘 2,400 次查詢。 | 在 Google Cloud 專案的 Admin SDK API 配額頁面提高每位使用者的限制，或利用指數輪詢降低要求的傳送速率。 |
| 403 | quotaExceeded | 表示特定作業的並行要求數量已達上限。 | 使用指數輪詢重試。請降低傳送要求的速率。 |
| 429 | rateLimitExceeded | 表示特定作業的並行要求數量已達上限。 | 使用指數輪詢重試。您必須降低傳送要求的速率。這項限制是以 Google Workspace 帳戶為準，而非以 API 用戶端或每位使用者為單位。這項上限無法提高。 |
實行指數輪詢
指數輪詢是指用戶端定期重試失敗要求的程序，且要求數量會隨時間增加。這是網路應用程式的標準錯誤處理策略。使用指數輪詢可以提升頻寬用量的效率、減少取得成功回應所需的要求數，並盡可能提高並行環境中的要求總處理量。
實作簡單指數輪詢的流程如下。
- 向 API 提出要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 1 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 2 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 4 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 8 秒 +
random_number_milliseconds秒 - 重試要求
- 接收包含可重試錯誤代碼的錯誤回應
- 等待 16 秒 +
random_number_milliseconds秒 - 重試要求
- 如果持續發生錯誤，請停止並記錄錯誤。
在上述流程中，random_number_milliseconds 是小於或等於 1000 的隨機毫秒數。這是為了避免某些並行實作時發生特定鎖定錯誤。每次等待之後，都必須重新定義 random_number_milliseconds。
注意：等待時間一律是 (2 ^ n) + random_number_milliseconds，其中 n 是最初定義為 0 的單調遞增整數。對於每次疊代 (每個要求)，n 會遞增 1。
演算法已設定為會在 n 等於 5 時終止。此上限的用意只是防止用戶端無限重試，導致要求在總延遲時間達到約 32 秒之後，才會被視為「無法復原的錯誤」。如有需要，您的 API 用戶端可以實作更多嘗試。
API 限制與配額
| API 限制類別 | 限制 |
|---|---|
| 建立使用者 | 使用 Directory API 時，每個網域每秒最多只能建立 10 位使用者。 |
| 已將群組新增為其他群組的成員 | 下層群組的成員最多可能要過 10 分鐘，才會顯示為上層群組的成員。這項限制可能會因系統的容量而異。 |
| 行動裝置 |
使用 Directory API 即可執行下列作業：
|
| 重新命名使用者 | 最多可能需要 10 分鐘才能套用到所有服務。重新命名使用者之前，建議先將使用者登出所有瀏覽器工作階段和服務。詳情請參閱「更新使用者」。 |
| 建立/更新機構單位 |
|
| API 配額類別 | 配額 |
Chrome 裝置 annotatedLocation，最多字元
|
裝置位置資訊的長度上限為 200 個字元。 |
Chrome 裝置 notes，最多字元
|
裝置附註資訊的長度上限為 500 個字元。 |
Chrome 裝置，最多 user 個字元
|
裝置使用者名稱的長度上限為 100 個字元。 |
| 網域別名 (上限) | 網域別名的數量上限為 20 個。 |
| 群組、說明 | 說明的長度上限為 4,096 個字元。 |
| 每個帳戶的群組 | 如果您使用的是 G Suite 舊版 (免費版) 帳戶，群組數量限制為 10 個。其他版本的群組數量則沒有上限。 |
| 每個群組的成員數量 | 如果您使用的是 G Suite 舊版 (免費版) 帳戶，單一群組最多可以包含 100 位成員。其他版本則沒有單一群組的成員人數上限。 如要瞭解每位使用者的群組成員資格限制，請參閱瞭解網路論壇政策與使用限制 |
| maxResults 查詢字串 | API 會傳回：
|
| 多個網域，單一帳戶允許的網域數量上限 | 600 (1 個主網域 + 599 個額外網域) |
| 機構單位，一次移動的使用者人數上限 | 一次可以移動 20 位使用者。使用者的主要電子郵件地址必須已存在於帳戶中。 |
| 使用者別名 | 每個使用者帳戶最多可以有 30 個別名。 |
| 使用者別名 (使用已刪除的別名) | 刪除的使用者別名可立即再次使用。 |
| 其他限制類型 | 限制和規範 |
|---|---|
| 計費及建立使用者 | 如果是採用 Google Workspace 彈性方案的使用者，透過這個 API 建立使用者將會在收益方面產生影響，我們也會向您的客戶帳單帳戶收費。舉例來說，如果您採用 Google Workspace 彈性方案，建立 10 位使用者時，系統會向您的帳戶收取 10 個 Google Workspace 授權的費用，並且按比例計算費用。如果採用年約方案，您本身就已綁約購買特定數量的授權，而且根據合約可建立的使用者人數有限。如要進一步瞭解計費方案和帳單帳戶，請參閱管理說明中心。 |
| 姓名 | 名字和姓氏的長度上限為 40 個半形字元。支援 Unicode/UTF-8 字元，而且可包含空格、英文字母 (a-z)、數字 (0-9)、破折號 (-)、正斜線 (/) 和半形句號 (.)。如要進一步瞭解字元使用規則，請參閱管理說明中心。 |
| 群組、刪除 | 刪除群組並不會刪除群組成員的使用者帳戶。 |
| 群組和群組成員、電子郵件地址變更 | 在這個版本中，您可以在 Google Workspace 服務啟用前變更群組的電子郵件地址。您可以透過管理控制台變更群組成員的電子郵件地址。一旦變更，API 就會自動反映電子郵件地址的變更。 |
| 群組、設定 | 您可透過管理控制台管理群組存取權設定、共用選項、監控和討論封存資料。如要進一步瞭解群組設定，請參閱管理說明中心。 |
| 群組、傳送訊息 | 為了杜絕垃圾郵件和電子郵件濫用行為，Google 對您一次可傳送的郵件數量限制為外部收件者。如果您傳送郵件給群組，系統會將每位外部成員視為一位收件者。詳情請參閱電子郵件傳送限制和避免寄給 Gmail 使用者的郵件遭到封鎖或歸類為垃圾郵件 。 |
| 群組，傳送 NDR 訊息 | 您無法將未傳遞回條 (NDR，也稱為「退回郵件」) 傳送或轉寄給群組。 |
| 使用者建立的群組 (限制) | 如需瞭解使用者建立的群組限制，請參閱管理說明中心 |
| 機構單位，開啟/關閉服務 | 您可以使用管理控制台管理特定機構單位的開啟或關閉服務。 |
| 密碼 | 可以包含任何字元組合。至少須輸入 8 個字元。長度上限為 100 個半形字元。 |
| 相片 | 在這個版本的 API 中，相片是使用者最新的 Google 個人資料相片。 |
| 使用者名稱 | 使用者名稱可以包含英文字母 (a 至 z)、數字 (0 至 9)、連字號 (-)、底線 (_) 和 Google Workspace 可辨識半形句號或半形句號 (.)，與 Gmail 不同。使用者名稱不得包含等號 (=)、方括號 (<、>) 或連續多個半形句號 (.)。詳情請參閱管理說明中心。 |
| 使用者名稱、重新命名 | 重新命名後，Google Hangouts 會捨棄所有已儲存的即時通訊邀請。使用者必須要求取得權限，才能再次與好友進行即時通訊。系統會保留舊使用者名稱做為電子郵件別名，以確保電子郵件轉寄設定可持續傳送郵件，且無法將 <使用者名稱> 做為新的使用者名稱。如要進一步瞭解重新命名使用者的影響，請參閱管理說明中心。重新命名後，使用「刪除使用者的別名」作業移除電子郵件別名。 |
| 多個網域的使用者 | Google Workspace 帳戶可包含您的任一網域，使用多個網域帳戶時，其中一個網域的使用者皆可與其他帳戶網域的使用者共用服務。多個網域元件如下：
|
| 警告，群組成員 | GROUP_CANNOT_CONTAIN_CYCLE：此 API 不允許循環套用群組成員資格。舉例來說，如果 group1 是 group2 成員，就不能是 group1 成員。 |