处理 API 错误

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

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

本页的其余部分提供了日历错误参考信息，并就如何在应用中处理这些错误提供了一些指导。

实现指数退避

Cloud API 文档详细说明了指数退避以及如何将其与 Google API 搭配使用。

错误和建议的操作

本部分提供了所列出的每种错误的完整 JSON 表示法，以及您可能采取的建议操作。

400：错误请求

用户错误。这可能意味着未提供必需的字段或参数、提供的值无效，或者所提供字段的组合无效。

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "timeRangeEmpty",
    "message": "The specified time range is empty.",
    "locationType": "parameter",
    "location": "timeMax",
   }
  ],
  "code": 400,
  "message": "The specified time range is empty."
 }
}

建议的操作：由于这是一个永久性错误，请勿重试。 请改为阅读错误消息，并相应地更改您的请求。

401：凭据无效

授权标头无效。 您使用的访问令牌已过期或无效。

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

建议采取的操作：

  • 使用长期有效的刷新令牌获取新的访问令牌。
  • 如果此操作失败，请按照使用 OAuth 2.0 授权请求中所述，引导用户完成 OAuth 流程。
  • 如果您看到的是服务账号的此错误，请检查您是否已成功完成服务账号页面中的所有步骤。

403：已超出用户速率限制

已达到 Play 管理中心中的某项限制。

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

建议采取的操作：

403：已超出速率限制

用户已达到 Google 日历 API 的每个日历或每个经过身份验证的用户的最大请求速率。

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

建议的操作： rateLimitExceeded 错误可能会返回 403 或 429 错误代码，目前它们在功能上类似，应以相同的方式进行响应，即使用指数退避。此外，请确保您的应用遵循管理配额中的最佳实践。

403：已超出日历使用量限制

用户达到了 Google 日历使用量上限，此上限旨在保护 Google 用户和基础架构免受滥用行为的影响。

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

建议采取的操作：

403：非组织者禁止访问

活动更新请求尝试在非组织者的副本中设置共享活动属性。共享属性（例如 guestsCanInviteOthers、guestsCanModify 或 guestsCanSeeOtherGuests）只能由组织者设置。

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "forbiddenForNonOrganizer",
    "message": "Shared properties can only be changed by the organizer of the event."
   }
  ],
  "code": 403,
  "message": "Shared properties can only be changed by the organizer of the event."
 }
}

建议采取的操作：

  • 如果您使用的是 Events: insert、Events: import 或 Events: update，并且您的请求不包含任何共享属性，则这相当于尝试将这些属性设置为其默认值。建议改用 Events: patch。
  • 如果您的请求具有共享属性，请确保您仅在更新组织者的副本时尝试更改这些属性。

404：未找到

找不到指定的资源。这种情况可能会在以下几种情况下发生。 下面是一些示例：

  • 当所请求的资源（具有所提供的 ID）从未存在过时

  • 当用户访问其无法访问的日历时

    { "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "未找到" } ], "code": 404, "message": "未找到" } }

建议执行的操作：使用指数退避算法。

409：所请求的标识符已存在

存储空间中已存在具有指定 ID 的实例。

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "duplicate",
    "message": "The requested identifier already exists."
   }
  ],
  "code": 409,
  "message": "The requested identifier already exists."
 }
}

建议的操作：如果您想创建新实例，请生成新 ID；否则，请使用 update 方法调用。

409：冲突

由于与请求的其他批处理项存在操作冲突，events.batch 操作中的批处理项无法执行。

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conflict",
    "message": "Conflict"
   }
  ],
  "code": 409,
  "message": "Conflict"
 }
}

建议采取的措施：排除所有成功完成和所有确定失败的批处理项，然后尝试使用不同的 events.batch 或相应的单次事件操作重试剩余的项。

410：已删除

syncToken 或 updatedMin 参数不再有效。如果请求尝试删除已删除的事件，也会发生此错误。

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "fullSyncRequired",
    "message": "Sync token is no longer valid, a full sync is required.",
    "locationType": "parameter",
    "location": "syncToken",
    }
  ],
  "code": 410,
  "message": "Sync token is no longer valid, a full sync is required."
 }
}

或

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "updatedMinTooLongAgo",
    "message": "The requested minimum modification time lies too far in the past.",
    "locationType": "parameter",
    "location": "updatedMin",
   }
  ],
  "code": 410,
  "message": "The requested minimum modification time lies too far in the past."
 }
}

或

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "deleted",
    "message": "Resource has been deleted"
   }
  ],
  "code": 410,
  "message": "Resource has been deleted"
 }
}

建议执行的操作：对于 syncToken 或 updatedMin 参数，请清空商店并重新同步。如需了解详情，请参阅高效同步资源。 对于已删除的活动，您无需采取任何进一步的措施。

412：前提条件失败

If-match 标头中提供的 etag 不再与资源的当前 etag 对应。

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conditionNotMet",
    "message": "Precondition Failed",
    "locationType": "header",
    "location": "If-Match",
    }
  ],
  "code": 412,
  "message": "Precondition Failed"
 }
}

建议的操作：重新提取实体并重新应用更改。如需了解详情，请参阅获取特定版本的资源。

429：请求数过多

如果用户在给定时间内发送的请求过多，就会出现 rateLimitExceeded 错误。

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

建议的操作： rateLimitExceeded 错误可能会返回 403 或 429 错误代码，目前它们在功能上类似，应以相同的方式进行响应，即使用指数退避。此外，请确保您的应用遵循管理配额中的最佳实践。

500：后端错误

处理请求时发生意外错误。

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

建议执行的操作：使用指数退避算法。