限额和配额可保护 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)、短划线 (-)、正斜线 (/) 和英文句点 (.)。如需详细了解字符使用规则，请参阅管理帮助中心。 |
| 群组，删除 | 删除群组不会删除群组成员的用户账号。 |
| 群组和群组成员、电子邮件地址变更 | 在此版本的 API 中，可以在启用 Google Workspace 服务之前更改群组的电子邮件地址。使用 Google 管理控制台更改群组成员的电子邮件地址。更改完成后，API 会自动反映电子邮件地址的更改。 |
| 群组、设置 | 群组访问权限设置、共享选项、监控和讨论归档内容均通过 Google 管理控制台进行管理。如需详细了解群组设置，请参阅管理帮助中心。 |
| 群组，发送消息 | 为遏制垃圾邮件和电子邮件滥用行为，Google 会限制您一次可向外部收件人发送的邮件数量。如果您向群组发送邮件，每位外部成员都会被计为一位收件人。如需了解详情，请参阅电子邮件发送限制和防止发送给 Gmail 用户的邮件遭到屏蔽或被列为垃圾邮件 。 |
| 群组，发送 NDR 消息 | 您不能将无法递送回执（NDR，也称为“退回邮件”）发送或转发至群组。 |
| 用户创建的群组，限制 | 如需了解用户创建的群组的限制，请参阅管理帮助中心 |
| 组织部门，开启/关闭服务 | 您可以使用 Google 管理控制台来管理组织部门的服务启用和停用。 |
| 密码 | 可以包含任意字符组合。不得少于 8 个字符。长度上限为 100 个字符。 |
| 照片 | 在此版本的 API 中，照片是指用户的最新 Google 个人资料照片。 |
| 用户名 | 用户名可以包含字母 (a-z)、数字 (0-9)、短划线 (-)、下划线 (_) 和英文句点 (.)。这与 Gmail 不同。用户名不得包含等号 (=)、尖括号 (<,>) 或连续多个英文句号 (.)。如需了解详情，请访问管理帮助中心。 |
| 用户名、重命名 | 在重命名后，Google Hangouts 会舍弃所有已记住的聊天邀请。用户必须再次请求与好友聊天的权限。旧用户名会作为电子邮件别名保留，以确保在设置了电子邮件转发的情况下能继续收发邮件，但不能用作新用户名。如需详细了解重命名用户的影响，请参阅管理帮助中心。重命名后，使用删除用户的别名操作移除电子邮件别名。 |
| 多个网域中的用户 | Google Workspace 账号可以包含您的任何网域。在多网域账号中，一个网域中的用户可以与其他账号网域中的用户共享服务。多个网域组件包括：
|
| 警告、群组成员 | GROUP_CANNOT_CONTAIN_CYCLE - API 不允许群组成员关系中存在环路。例如，如果 group1 是 group2 的成员，则 group2 不能是 group1 的成员。 |