处理 API 错误

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

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

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

实现指数退避算法

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 流程，如使用 OAuth 2.0 授权请求中所述。
  • 如果您看到服务账号存在此问题，请检查您是否已成功完成“服务账号”页面中的所有步骤。

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": "Not Found" } ], "code": 404, "message": "Not Found" } }

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

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

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