Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

解决错误

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）共用。如果您超出这些限制，API 会返回 HTTP 429 错误“Too many requests: User-rate limit exceeded (Mail sending)”，并提供重试时间。超出每日限制可能会导致这些错误持续数小时，之后服务器才会接受请求。

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

带宽限制

该 API 具有与 IMAP 相同但独立的每用户上传和下载带宽限制。这些限额适用于用户的所有 Gmail API 客户端。

用户通常只会在特殊情况或滥用情况下遇到这些限制。如果超出这些限制，API 会返回 HTTP 429 错误“Too many requests: User-rate limit exceeded”（请求过多：用户速率限制已超出），并提供重试时间。如果超出每日限额，服务器可能在数小时内都无法接受请求，从而导致这些错误。

并发请求

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

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

500、502、503、504 错误

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

以下是 5xx 错误的列表：

500 后端错误
502 网关无效
503 服务不可用
504 网关超时

`backendError`

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

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

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

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

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

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

管理配额限制

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

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

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

批量请求

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