解决错误

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

如需修复此错误，请使用长期有效的刷新令牌刷新访问令牌。如果您使用的是客户端库，则该库会自动处理令牌刷新。如果此操作失败，请按照使用 Gmail 授权应用中所述，引导用户完成 OAuth 流程。

如需详细了解 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 客户端、原生/Web 客户端还是 SMTP MSA）共用。如果超出这些限制，系统会返回 HTTP 429 错误 Too Many Requests“User-rate limit exceeded”“(Mail sending)”，并附带重试时间。 请注意，如果超出每日限额，可能会导致在请求被接受之前的数小时内出现这些类型的错误。

邮件发送流水线非常复杂：一旦用户超出配额，API 可能需要等待几分钟才会开始返回 429 错误响应。因此，您不能假设 200 响应表示电子邮件已成功发送。

带宽限制

该 API 具有与 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 秒再重试，然后等待 2 秒再重试，最后等待 4 秒再重试。此方法称为指数退避，用于提高带宽使用效率，并最大程度地提高并发环境中的请求吞吐量。

在发生错误后至少一秒开始重试。

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

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

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

批量请求

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