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 个请求。如需了解如何批量处理请求,请参阅批量处理请求。