此页面由 Cloud Translation API 翻译。

处理 API 错误

日历 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 流程，如使用 OAuth 2.0 为请求授权。
如果服务账号出现此错误消息，请检查已成功完成服务账号页面。

403：超出用户速率限制

已达到开发者控制台提供的某项限制。

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

建议采取的措施：

确保您的应用遵循管理配额。
在 Developer Console 项目中提高每位用户的配额。
如果某位用户代表某个网站上的许多用户 Google Workspace 账号，请考虑使用使用启用了全网域授权功能的服务账号并设置 quotaUser 参数。
使用指数退避算法。

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

建议采取的措施：

如需详细了解日历用量限额，请参阅 Google Workspace 管理员帮助。

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

建议采取的措施：

如果您使用的是事件：insert，事件：import 或 Events: update，并且请求不包含这等同于尝试将它们设为默认值。考虑使用事件：patch 。
如果您的请求包含共享资源，请确保您只是尝试如果您要更新组织者的副本，请更改这些属性。

404：未找到

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

当请求的资源（具有提供的 ID）从未存在时
访问用户无法访问的日历时

{ "error": { "errors": [ { "domain": "全球", "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：冲突

某一个 Pod 内的 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"
  }
}

500：后端错误

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

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

建议采取的措施：使用指数退避算法。