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 流程,如使用 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 Calendar 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 日历的用量限额,请访问 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."
}
}
建议采取的措施:
- 如果您使用的是 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"
}
}
建议采取的措施:使用指数退避算法。