Gmail API 会返回两级错误信息：
- 标头中的 HTTP 错误代码和消息。
- 响应正文中的 JSON 对象，包含可帮助您确定如何处理错误的更多详细信息。
Gmail 应用应捕获并处理使用 REST API 时可能遇到的所有错误。本指南介绍了如何解决特定 API 错误。
解决 400 错误：请求错误
此错误可能是由您的代码这些错误导致的：
- 未提供必填字段或参数。
- 提供的值无效或提供的字段组合无效。
- 附件无效。
以下是此错误的 JSON 表示示例：
{
"error": {
"code": 400,
"errors": [
{
"domain": "global",
"location": "orderBy",
"locationType": "parameter",
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
"reason": "badRequest"
}
],
"message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
}
}
如需修正此错误，请检查 message 字段并相应地调整您的代码。
解决 401 错误：凭据无效
401 错误表示您使用的访问令牌已过期或无效。此错误也可能是由于所请求范围的授权缺失所致。以下是此错误的 JSON 表示形式：
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
如需修复此错误，请使用长期刷新令牌刷新访问令牌。如果您使用的是客户端库，它会自动处理令牌刷新。如果失败，请引导用户完成 OAuth 流程，如使用 Gmail 授权应用中所述。
如需详细了解 Gmail 限制，请参阅用量限额。
解决 403 错误：超出用量限额
当超出用量限额或用户没有正确的权限时，会发生 403 错误。如需确定具体的错误类型，请评估所返回的 JSON 的 reason 字段。在以下情况下，会出现此错误：
- 超出了每日上限。
- 已超出用户速率限制。
- 已超出项目速率限制。
- 您的应用无法在已通过身份验证的用户的网域内使用。
如需详细了解 Gmail 限制，请参阅用量限额。
解决 403 错误：已超出每日上限
dailyLimitExceeded 错误表示您的项目已达到礼节性 API 限制。以下是此错误的 JSON 表示形式：
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
要修复此错误，请执行以下操作：
- 访问 Google API 控制台
- 选择您的项目。
- 点击配额标签页
- 申请更多配额。如需了解详情，请参阅申请更多配额。
如需详细了解 Gmail 限制，请参阅用量限额。
解决 403 错误：已超出用户速率限制
userRateLimitExceeded 错误表示已达到每个用户的限制。以下是此错误的 JSON 表示法：
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
如需修复此错误，请尝试优化应用代码以减少发出的请求或重试请求。如需了解如何重试请求，请参阅重试失败的请求以解决错误。
如需详细了解 Gmail 限制，请参阅用量限额。
解决 403 错误：已超出速率限制
rateLimitExceeded 错误表示用户已达到 Gmail API 的请求速率上限。此限制因请求的类型而异。以下是此错误的 JSON 表示形式：
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
如需修正此错误，请重试失败的请求。
如需详细了解 Gmail 限制，请参阅用量限额。
解决 403 错误：无法在经过身份验证的用户的网域内使用 ID 为 {appId} 的应用
如果用户网域的政策不允许您的应用访问 Gmail，则会出现 domainPolicy 错误。以下是此错误的 JSON 表示形式：
{
"error": {
"errors": [
{
"domain": "global",
"reason": "domainPolicy",
"message": "The domain administrators have disabled Gmail apps."
}
],
"code": 403,
"message": "The domain administrators have disabled Gmail apps."
}
}
要修复此错误，请执行以下操作：
- 告知用户该网域不允许您的应用访问 Gmail。
- 指示用户联系网域管理员，为您的应用请求访问权限。
解决 429 错误：请求过多
由于每位用户每日限制（包括邮件发送限制）、带宽限制或每用户的并发请求限制，可能会发生 429“请求过多”错误。有关各项限制的信息如下。但是，您可以通过尝试重试失败的请求或将处理作业拆分到多个 Gmail 帐号来解决各种限制。每位用户的限制无法因任何原因提高。如需详细了解限制，请参阅用量限额。
邮件发送限额
Gmail API 会强制执行标准的每日邮件发送限制。付费用户和试用 gmail.com 用户的 Google Workspace 上限有所不同。如需了解这些限制，请参阅 Google Workspace中的 Gmail 发信上限。
这些限制针对每位用户，由用户的所有客户端（API 客户端、原生/Web 客户端或 SMTP MSA）共享。如果超出这些限制，系统会返回 HTTP 429 Too Many Requests“User-rate limit exceeded”“（邮件发送）”错误，并提供重试时间。请注意，如果超出每日限制，可能会导致在系统接受请求之前的几个小时内，出现这些类型的错误。
邮件发送流水线非常复杂：用户超出配额后，API 可能会延迟几分钟才开始返回 429 错误响应。因此，您不能假定 200 响应表示电子邮件已成功发送。
带宽限制
该 API 具有针对每位用户的上传和下载带宽限制，这些限制等于但独立于 IMAP。这些限制在给定用户的所有 Gmail API 客户端之间共享。
通常只有在特殊情况或滥用情况下才会达到这些限制。
如果超出这些限制，系统会返回 HTTP 429 Too Many Requests“超出用户速率上限”错误，并提供重试时间。请注意，如果超出每日限制，可能会导致在系统接受请求之前，这些类型的错误在几个小时后才会被接受。
并发请求
除了每位用户的速率限制之外，Gmail API 还实施了每位用户的并发请求限制。访问给定用户的所有 Gmail API 客户端均受此限制，可确保没有任何 API 客户端导致 Gmail 用户邮箱或其后端服务器过载。
如果针对单个用户发出许多并行请求，或者批量发送大量请求，都可能会触发此错误。同时访问 Gmail 用户邮箱的大量独立 API 客户端也可能会触发此错误。如果超出此限制，则系统会返回 HTTP 429 Too Many Requests“用户的并发请求过多”错误。
解决 500 错误：后端错误
如果在处理请求时发生意外错误，则会发生 backendError。
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
如需修正此错误，请重试失败的请求。以下是 500 错误的列表：
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
重试失败的请求以解决错误
您可以增加一段时间内定期重试失败的请求，以处理与速率限制、网络量或响应时间相关的错误。例如，您可以在一秒后重试失败的请求，然后在两秒后重试，然后四秒后重试。此方法称为指数退避算法，用于提高带宽使用率并最大限度地提高并发环境中的请求吞吐量。
在错误发生至少一秒后开始重试周期。
查看或更改用量限额，增加配额
如需查看或更改项目的用量限额，或申请增加配额，请执行以下操作：
- 如果您的项目还没有结算账号，请创建一个。
- 在 API 控制台中访问 API 库中的“已启用的 API”页面，然后从列表中选择一个 API。
- 如需查看和更改配额相关设置，请选择配额。如需查看使用量统计信息，请选择使用量。
批量请求
建议使用批处理，不过，较大的批次大小可能会触发速率限制。不建议批量发送超过 50 个请求。如需了解如何批量处理请求，请参阅批量处理请求。