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

Switch to English

오류 해결

Google Drive API는 다음 두 가지 오류 정보를 반환합니다.

헤더의 HTTP 오류 코드 및 메시지
응답 본문에서 오류 처리 방법을 결정하는 데 도움이 되는 추가 세부정보가 포함된 JSON 객체입니다.

Drive 앱은 REST API를 사용할 때 발생할 수 있는 모든 오류를 포착하고 처리해야 합니다. 이 가이드에서는 특정 API 오류를 해결하는 방법을 설명합니다.

400 오류 해결: 잘못된 요청

이 오류는 코드에서 다음 문제 중 하나로 인해 발생할 수 있습니다.

필수 필드 또는 매개변수가 제공되지 않았습니다.
제공된 값 또는 제공된 필드의 조합이 잘못되었습니다.
Drive 파일에 중복 상위 항목을 추가하려고 했습니다.
디렉터리 그래프에 주기를 만드는 상위 요소를 추가하려고 했습니다.

다음은 이 오류의 샘플 JSON 표현입니다.

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

이 오류를 수정하려면 message 필드를 확인하고 그에 따라 코드를 조정하세요.

400 오류 해결: 잘못된 공유 요청

이 오류는 여러 가지 이유로 발생할 수 있습니다. 초과된 한도를 확인하려면 반환된 JSON의 reason 필드를 평가합니다. 이 오류는 일반적으로 다음과 같은 경우에 발생합니다.

공유에 성공했지만 알림 이메일이 올바르게 전송되지 않았습니다.
이 사용자는 액세스 제어 목록 (ACL)을 변경할 수 없습니다.

message 필드는 실제 오류를 나타냅니다.

공유에 성공했지만 알림 이메일이 올바르게 전송되지 않음

다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"Sorry, the items were successfully shared but emails could not be sent to email@domain.com.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

이 오류를 해결하려면 공유하려는 이메일 주소로 알림 이메일을 보낼 수 없기 때문에 사용자 (공유자)에게 공유할 수 없다고 알립니다. 사용자는 이메일 주소가 올바른지, 이메일을 받을 수 있는지 확인해야 합니다.

이 사용자는 ACL을 변경할 수 없습니다.

다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidSharingRequest",
        "message": "Bad Request. User message: \"ACL change not allowed.\""
      }
    ],
    "code": 400,
    "message": "Bad Request"
  }
}

이 오류를 해결하려면 파일이 속한 도메인의 Google Workspace 공유 설정을 확인하세요. 이 설정은 도메인 외부 공유를 금지하거나 공유 드라이브 공유가 허용되지 않을 수 있습니다.

401 오류 해결: 잘못된 사용자 인증 정보

401 오류는 사용 중인 액세스 토큰이 만료되었거나 잘못되었음을 나타냅니다. 이 오류는 요청된 범위에 대한 승인 누락으로 인해 발생할 수도 있습니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

이 오류를 해결하려면 장기 갱신 토큰을 사용하여 액세스 토큰을 새로고침하세요. 이 방법이 실패하면 API 관련 승인 및 인증 정보에 설명된 대로 OAuth 흐름을 통해 사용자를 안내합니다.

403 오류 해결

오류 403은 사용량 한도를 초과했거나 사용자에게 올바른 권한이 없는 경우에 발생합니다. 구체적인 오류 유형을 확인하려면 반환된 JSON의 reason 필드를 평가합니다. 이 오류는 다음과 같은 경우에 발생합니다.

일일 한도를 초과했습니다.
사용자 비율 제한을 초과했습니다.
프로젝트 비율 제한을 초과했습니다.
공유 비율 한도를 초과했습니다.
사용자가 앱에 앱 권한을 부여하지 않았습니다.
사용자에게 파일에 대한 권한이 없습니다.
로그인한 사용자의 도메인 내에서 앱을 사용할 수 없습니다.
폴더에 포함된 항목 수를 초과했습니다.

Drive API 한도에 관한 자세한 내용은 사용량 한도를 참고하세요. Drive 폴더 한도에 관한 자세한 내용은 Google Drive의 폴더 한도를 참고하세요.

403 오류 해결: 일일 한도 초과

dailyLimitExceeded 오류는 프로젝트의 예외 인정 API 한도에 도달했음을 나타냅니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

이 오류는 애플리케이션 소유자가 특정 리소스의 사용량을 제한하도록 할당량 한도를 설정한 경우에 표시됩니다. 이 오류를 해결하려면 '일일 쿼리' 할당량의 사용량 한도를 삭제하세요.

403 오류 해결: 사용자 비율 한도 초과

userRateLimitExceeded 오류는 사용자별 한도에 도달했음을 나타냅니다. Google API 콘솔의 한도 또는 Drive 백엔드의 한도일 수 있습니다. 다음은 이 오류의 JSON 표현입니다.

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

이 오류를 해결하려면 다음 중 한 가지 방법을 시도해 보세요.

Google Cloud 프로젝트에서 사용자별 할당량 상향 조정 자세한 내용은 할당량 상향 조정을 요청하세요.

한 사용자가 많은 Google Workspace 계정 사용자를 대신하여 여러 요청을 하는 경우 quotaUser 매개변수를 사용하여 도메인 전체 위임이 있는 서비스 계정을 사용하는 것이 좋습니다.
지수 백오프를 사용하여 요청을 다시 시도하세요.

Drive API 한도에 관한 자세한 내용은 사용량 한도를 참고하세요.

403 오류 해결: 프로젝트 비율 한도 초과

rateLimitExceeded 오류는 프로젝트의 비율 한도에 도달했음을 나타냅니다. 이 한도는 요청 유형에 따라 다릅니다. 다음은 이 오류의 JSON 표현입니다.

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

이 오류를 해결하려면 다음 중 한 가지 방법을 시도해 보세요.

Google Cloud 프로젝트에서 사용자별 할당량 상향 조정 자세한 내용은 할당량 상향 조정을 요청하세요.
일괄 요청: API 호출 수를 줄입니다.
지수 백오프를 사용하여 요청을 다시 시도하세요.

403 오류 해결: 공유 비율 한도 초과

sharingRateLimitExceeded 오류는 사용자가 공유 한도에 도달하면 발생합니다. 이 오류는 이메일 한도와 관련이 있는 경우가 많습니다. 다음은 이 오류의 JSON 표현입니다.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "message": "Rate limit exceeded. User message: \"These item(s) could not be shared because a rate limit was exceeded: filename",
    "reason": "sharingRateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

이 오류를 수정하는 방법은 다음과 같습니다.

대용량 파일을 공유할 때는 이메일을 보내지 마세요.
한 사용자가 많은 Google Workspace 계정 사용자를 대신하여 여러 요청을 하는 경우 quotaUser 매개변수를 사용하여 도메인 전체 위임이 있는 서비스 계정을 사용하는 것이 좋습니다.

403 오류 해결: 저장용량 한도 초과

storageQuotaExceeded 오류는 사용자가 저장용량 한도에 도달하면 발생합니다. 다음은 이 오류의 JSON 표현입니다.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "message": "The user's Drive storage quota has been exceeded.",
    "reason": "storageQuotaExceeded",
   }
  ],
  "code": 403,
  "message": "The user's Drive storage quota has been exceeded."
 }
}

이 오류를 수정하는 방법은 다음과 같습니다.

Drive 계정의 저장용량 한도를 검토합니다. 자세한 내용은 Drive 스토리지 및 업로드 한도를 참고하세요.
공간 절약하기

또는 Google One에서 추가 스토리지를 구매하세요.

403 오류 해결: 사용자가 {appId} {verb} 앱에 {fileId} 파일에 대한 액세스 권한을 부여하지 않았습니다.

appNotAuthorizedToFile 오류는 앱이 파일의 ACL에 없으면 발생합니다. 이 오류로 인해 사용자가 앱에서 파일을 열 수 없습니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "appNotAuthorizedToFile",
        "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user has not granted the app {appId} {verb} access to the file {fileId}."
  }
}

이 오류를 해결하려면 다음 중 한 가지 방법을 시도해 보세요.

Google Drive 선택 도구를 열고 사용자에게 파일을 열라는 메시지를 표시합니다.
사용자에게 앱의 Drive UI에서 연결 프로그램 컨텍스트 메뉴를 사용하여 파일을 열도록 안내합니다.

파일의 isAppAuthorized 필드를 확인하여 앱에서 파일을 만들거나 열었는지 확인할 수도 있습니다.

403 오류 해결: 사용자에게 {fileId} 파일에 대한 권한이 없습니다.

insufficientFilePermissions 오류는 사용자에게 파일에 대한 쓰기 액세스 권한이 없고 앱이 파일을 수정하려고 할 때 발생합니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "insufficientFilePermissions",
        "message": "The user does not have sufficient permissions for file {fileId}."
      }
    ],
    "code": 403,
    "message": "The user does not have sufficient permissions for file {fileId}."
  }
}

이 오류를 해결하려면 사용자에게 파일 소유자에게 문의하여 수정 권한을 요청하도록 안내하세요. files.get로 검색한 메타데이터에서 사용자 액세스 수준을 확인하고 권한이 없는 경우 읽기 전용 UI를 표시할 수도 있습니다.

403 오류 해결: ID가 {appId}인 앱은 인증된 사용자의 도메인 내에서 사용할 수 없습니다.

domainPolicy 오류는 사용자 도메인의 정책이 앱에서 Drive에 대한 액세스를 허용하지 않는 경우에 발생합니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Drive apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Drive apps."
  }
}

이 오류를 수정하는 방법은 다음과 같습니다.

도메인에서 앱이 Drive의 파일에 액세스하도록 허용하지 않는다고 사용자에게 알립니다.
도메인 관리자에게 문의하여 앱 액세스를 요청하도록 사용자에게 안내합니다.

403 오류 해결: 폴더의 항목 수를 초과했습니다.

numChildrenInNonRootLimitExceeded 오류는 폴더의 하위 요소 수 (폴더, 파일, 단축키)의 한도를 초과하면 발생합니다. 폴더에 직접 포함된 폴더,파일, 바로가기는 최대 500, 000개 항목으로 제한됩니다. 하위 폴더에 중첩된 항목은 이 500,000개 항목 한도에 포함되지 않습니다. Drive 폴더 한도에 관한 자세한 내용은 Google Drive의 폴더 한도를 참고하세요.

403 오류 해결: 계정에서 만든 항목의 수가 초과되었습니다.

휴지통에 있는지 여부에 관계없이 이 계정에서 만든 항목 수의 한도를 초과하면 activeItemCreationLimitExceeded 오류가 발생합니다. 폴더를 포함한 모든 항목 유형이 한도 계산에 포함됩니다.

404 오류 해결: 파일을 찾을 수 없음: {fileId}

notFound 오류는 사용자에게 파일에 대한 읽기 액세스 권한이 없거나 파일이 없는 경우에 발생합니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "File not found {fileId}"
      }
    ],
    "code": 404,
    "message": "File not found: {fileId}"
  }
}

이 오류를 수정하는 방법은 다음과 같습니다.

사용자에게 파일에 관한 읽기 액세스 권한이 없거나 파일이 존재하지 않는다고 알립니다.
사용자에게 파일 소유자에게 연락하여 파일 권한을 요청하라고 안내합니다.

429 오류 해결: 요청이 너무 많음

rateLimitExceeded 오류는 사용자가 지정된 시간 동안 너무 많은 요청을 보내면 발생합니다.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "rateLimitExceeded",
        "message": "Rate Limit Exceeded"
      }
    ],
    "code": 429,
    "message": "Rate Limit Exceeded"
  }
}

이 오류를 수정하려면 지수 백오프를 사용하여 요청을 다시 시도하세요.

5xx 오류 해결

5xx 오류는 요청을 처리하는 동안 예상치 못한 오류가 발생하는 경우 발생합니다. 이는 요청의 시간이 다른 요청과 중복되거나 지원되지 않는 작업 요청(예: 사이트 자체가 아닌 Google 사이트의 단일 페이지에 관한 권한 업데이트 시도)을 비롯한 다양한 문제로 인해 발생할 수 있습니다.

이 오류를 수정하려면 지수 백오프를 사용하여 요청을 다시 시도하세요. 다음은 5xx 오류 목록입니다.

500 백엔드 오류
502 잘못된 게이트웨이
503 서비스를 사용할 수 없음
504 게이트웨이 시간 초과