處理 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 流程，如使用 OAuth 2.0 授權要求中所述。
  • 如果您看到服務帳戶的狀態，請確認是否已順利完成服務帳戶頁面中的所有步驟。

403：超過使用者頻率限制

已達到開發人員控制台的其中一項限制。

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

建議採取的行動：

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

建議採取的行動：

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，且要求不含任何共用屬性，這相當於嘗試將屬性設為預設值。請考慮改用事件：patch。
  • 如果您的要求包含共用屬性，只有在您更新發起人的副本時，才嘗試變更這些屬性。

404：找不到

找不到指定的資源。在某些情況下，可能會發生這種情況。例如：

  • 當要求的資源 (具有提供的 ID) 不存在時

  • 存取使用者無法存取的日曆時

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

建議動作：使用指數輪詢。

409：要求的 ID 已存在

儲存空間中已有 ID 相同的執行個體。

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

建議動作：如要建立新的執行個體，請產生一個新的 ID，否則請使用 update 方法呼叫。

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

建議動作：使用指數輪詢。