이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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 2.0으로 요청 승인에 설명된 대로 사용자에게 OAuth 흐름을 안내합니다.
서비스 계정에 대해 이 오류가 표시되면 서비스 계정 페이지에서 모든 단계를 완료했는지 확인하세요.

403: 사용자 비율 제한 초과

Play Console에서 한도 중 하나에 도달했습니다.

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

권장 조치:

앱이 할당량 관리의 권장사항을 준수하는지 확인합니다.
Play 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 Calendar 한도 중 하나에 도달했습니다.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

권장 조치:

Calendar 사용량 한도에 대한 자세한 내용은 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: patch를 사용하는 것이 좋습니다.
요청에 공유 속성이 포함된 경우 주최자의 사본을 업데이트하는 경우에만 이러한 속성을 변경하려고 해야 합니다.

404: 찾을 수 없음

지정된 리소스를 찾을 수 없습니다. 이는 여러 가지 경우에 발생할 수 있습니다. 예를 들면 다음과 같습니다.

요청된 리소스 (제공된 ID 포함)가 존재하지 않을 때
사용자가 액세스할 수 없는 캘린더에 액세스할 때

{ "error": { "errors": [ { "domain": "global", "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 메서드 호출을 사용하세요.

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

권장 조치: 지수 백오프를 사용하세요.