解决错误

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"
  }
}

如需修正此错误，请执行以下操作：

  1. 访问 Google API 控制台
  2. 选择您的项目。
  3. 点击配额标签页
  4. 申请更多配额。如需了解详情，请参阅申请更多配额。

如需详细了解 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."
  }
}

如需修正此错误，请执行以下操作：

  1. 告知用户该网域不允许您的应用访问 Gmail。
  2. 请指示用户与网域管理员联系，申请对您的应用的访问权限。

解决 429 错误：请求过多

由于每位用户的每日限制（包括邮件发送限制）、带宽限制或每位用户的并发请求数限制，可能会出现 429“请求过多”错误。以下是有关每项限制的信息。不过，您可以通过尝试重试失败的请求或将处理工作拆分到多个 Gmail 账号来解决每个限制。无论出于何种原因，每位用户的限额都无法提高。如需详细了解限制，请参阅使用限制。

邮件发送限制

Gmail API 会强制执行标准的每日邮件发送限制。付费用户和试用 gmail.com 用户的这些限制有所不同。 如需了解这些限制，请参阅 中的 Gmail 发信上限。

这些限制是按用户设置的，并且会由用户的所有客户端共享，无论是 API 客户端、原生/网站客户端还是 SMTP MSA。如果超出这些限制，系统会返回 HTTP 429 Too Many Requests“用户速率上限已超”(Mail sending) 错误，并附带重试时间。请注意，如果超出每日限制，系统可能会在接受请求之前数小时内持续返回此类错误。

邮件发送流水线很复杂：用户超出配额后，API 可能需要延迟几分钟才能开始返回 429 错误响应。因此，您不能假定 200 响应表示电子邮件已成功发送。

带宽限制

该 API 具有每位用户的上传和下载带宽限制，该限制与 IMAP 相同，但独立于 IMAP。这些限制会在给定用户的所有 Gmail API 客户端中共享。

通常只有在出现异常情况或滥用行为时，才会达到这些限制。 如果超出这些限制，系统会返回 HTTP 429 Too Many Requests“用户速率限制超出”错误，并附带重试时间。请注意，如果超出每日限制，系统可能会在接受请求之前数小时内持续返回此类错误。

并发请求

除了每位用户的速率限制之外，Gmail API 还会强制执行每位用户的并发请求数限制。此限制由访问给定用户的所有 Gmail API 客户端共享，可确保没有 API 客户端会使 Gmail 用户邮箱或其后端服务器过载。

为单个用户发出多个并行请求或发送包含大量请求的批次可能会触发此错误。大量独立 API 客户端同时访问 Gmail 用户邮箱也可能会触发此错误。如果超出此限制，系统会返回 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

重试失败的请求以修正错误

您可以按照不断增加的时间间隔定期重试失败的请求，以处理与速率限制、网络流量或响应时间相关的错误。例如，您可以一秒后、两秒后、四秒后重试失败的请求。此方法称为指数退避，用于提高带宽使用效率，并最大限度地提高并发环境中的请求吞吐量。

在出现错误后至少 1 秒后开始重试周期。

查看或更改用量限制、增加配额

如需查看或更改项目的用量限制，或申请增加配额，请按以下步骤操作：

  1. 如果您的项目还没有结算账号，请创建一个。
  2. 在 API 控制台中访问 API 库中的“已启用的 API”页面，然后从列表中选择一个 API。
  3. 如需查看和更改配额相关设置，请选择配额。如需查看用量统计信息，请选择使用量。

批量请求

我们建议您使用批处理，但较大的批量大小可能会触发速率限制。不建议发送超过 50 个请求的批量。如需了解如何批量处理请求，请参阅批处理请求。