解决错误

Gmail API 会返回两个级别的错误信息：

标头中的 HTTP 错误代码和消息。
响应正文中的 JSON 对象，包含有助于您确定如何处理错误的其他详细信息。

Gmail 应用应捕获并处理使用 REST API 时可能遇到的所有错误。本指南介绍了如何解决特定的 Gmail API 错误。

HTTP 状态代码摘要

错误代码	说明
`200 - OK`	请求成功（这是成功 HTTP 请求的标准响应）。
`400 - Bad Request`	由于请求中存在客户端错误，无法完成请求。
`401 - Unauthorized`	请求包含无效的凭据。
`403 - Forbidden`	请求已收到并已理解，但用户无权执行该请求。
`404 - Not Found`	找不到所请求的网页。
`429 - Too Many Requests`	向 API 发出的请求过多。
`500, 502, 503, 504 - Server Errors`	处理请求时出现意外错误。

400 错误

这些错误表示请求存在错误，通常是由于缺少必需的参数。

`badRequest`

您的代码中存在以下任一问题都可能会导致此错误：

未提供必需的字段或参数。
提供的值或提供的字段组合无效。
附件无效。

以下 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 错误

这些错误表示请求不包含有效的访问令牌。

`authError`

当您使用的访问令牌已过期或无效时，会发生此错误。此错误也可能是由于缺少对所请求范围的授权而导致的。以下 JSON 示例表示此错误：

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

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

如需详细了解 Gmail 限制，请参阅用量限额。

403 错误

当您超出用量限额或用户没有正确的权限时，就会发生这些错误。如需确定原因，请评估返回的 JSON 的 reason 字段。此错误会在以下情况下发生：

您的应用无法在已通过身份验证的用户的网域中使用。
超出每日限额。
超出用户速率限制。
超出项目速率限制。

如需了解详情，请参阅使用限制。

`dailyLimitExceeded`

当项目达到 API 限制时，会发生此错误。以下 JSON 示例展示了此错误：

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

当应用的所有者设置了配额限制来限制特定资源的使用时，系统会显示此错误。如需修正此错误，请在 Google Cloud 项目中增加配额。如需了解详情，请参阅管理配额限制。

`domainPolicy`

如果用户网域的政策不允许您的应用访问 Gmail，就会出现此错误。以下 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。
指示用户与网域管理员联系，请求为您的应用授予访问权限。

`rateLimitExceeded`

此错误表示用户已达到 Gmail API 的最大请求速率。此限制因请求类型而异。以下 JSON 示例展示了此错误：

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
    }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
  }
}

如需修正此错误，请尝试以下操作：

申请增加配额。
使用指数退避算法重试请求。

`userRateLimitExceeded`

当达到每用户限制时，会发生此错误。以下 JSON 示例表示此错误：

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
    }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
  }
}

如需修正此错误，请尝试优化应用代码以减少请求次数，或使用指数退避算法重试请求。

429 错误数

429“请求过多”错误可能是由于每日每用户限制（包括邮件发送限制）、带宽限制或每用户并发请求限制而导致的。以下是有关每项限制的信息。不过，可以通过重试失败的请求或将处理任务分配到多个 Gmail 账号来解决每项限制。

无论出于何种原因，都无法提高每个用户的限额。如需详细了解限制，请参阅用量限额。

邮件发送限额

Gmail API 会强制执行标准每日邮件发送限额。付费 Google Workspace 用户和试用 gmail.com 用户的这些限制有所不同。如需了解这些限制，请参阅 Google Workspace 中的 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: User-rate limit exceeded”（请求过多：用户速率限制已超出），并提供重试时间。如果超出每日限额，可能会导致这些错误持续数小时，然后请求才会被接受。

并发请求

Gmail API 会强制执行每位用户的并发请求数限制（除了每位用户的速率限制之外）。此限制适用于访问用户的全部 Gmail API 客户端，可确保没有 API 客户端会使 Gmail 用户邮箱或其后端服务器过载。

为单个用户发出许多并行请求或发送包含大量请求的批次可能会触发此错误。大量独立的 API 客户端同时访问 Gmail 用户邮箱也可能会触发此错误。如果超出此限制，系统会返回 HTTP 429 错误“Too many requests: Too many concurrent requests for user”。

500、502、503、504 错误

在处理请求时出现意外服务器错误时，会发生这些错误。各种问题都可能会导致这些错误，包括请求的时间与另一个请求重叠，或者请求的操作不受支持，例如尝试更新 Google 协作平台中单个网页（而非整个网站）的权限。

以下是 5xx 错误的列表：

500 后端错误
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

backendError

处理请求时出现意外错误，就会发生此错误。以下 JSON 示例表示此错误：

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

如需修正此错误，请使用指数退避算法重试请求。

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

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

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

管理配额限制

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

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

如需了解详情，请参阅查看和管理配额。

批量请求

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