日历 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"
}
}
建议采取的措施:rateLimitExceeded
错误可能会返回 403 或 429
错误代码 - 目前它们的功能相似,
执行相同的操作,即使用指数退避算法。
此外,请确保您的应用遵循
管理配额。
500:后端错误
处理请求时发生意外错误。
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
建议采取的措施:使用指数退避算法。