Mengatasi error

Google Drive API menampilkan dua tingkat informasi error:

  • Kode error HTTP dan pesan header.
  • Objek JSON dalam isi respons dengan detail tambahan yang dapat membantu Anda menentukan cara menangani kesalahan.

Aplikasi Google Drive harus menangkap dan menangani semua error yang mungkin terjadi saat menggunakan REST API. Panduan ini berisi petunjuk tentang cara mengatasi error Drive API tertentu.

Ringkasan kode status HTTP

Kode error Deskripsi
200 - OK Permintaan berhasil (ini adalah respons standar untuk permintaan HTTP yang berhasil).
400 - Bad Request Permintaan tidak dapat dipenuhi karena terjadi error klien dalam permintaan.
401 - Unauthorized Permintaan berisi kredensial yang tidak valid.
403 - Forbidden Permintaan telah diterima dan dipahami, tetapi pengguna tidak memiliki izin untuk melakukan permintaan.
404 - Not Found Halaman yang diminta tidak dapat ditemukan.
429 - Too Many Requests Terlalu banyak permintaan ke API.
500, 502, 503, 504 - Server Errors Terjadi error yang tidak terduga saat memproses permintaan.

Error 400

Kesalahan ini menunjukkan bahwa permintaan tidak dapat diterima, sering kali karena parameter yang diperlukan.

badRequest

Error ini dapat terjadi karena salah satu masalah berikut di kode Anda:

  • Kolom atau parameter yang wajib diisi belum diberikan.
  • Nilai yang diberikan atau kombinasi kolom yang diberikan tidak valid.
  • Anda mencoba menambahkan induk duplikat ke file Drive.
  • Anda mencoba menambahkan induk yang akan membuat siklus di grafik direktori.

Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, periksa kolom message dan sesuaikan kode Anda.

invalidSharingRequest

Error ini terjadi karena beberapa alasan. Untuk menentukan penyebabnya, evaluasi Kolom reason dari JSON yang ditampilkan. Kesalahan ini paling sering terjadi karena:

  • Berbagi berhasil, tetapi email notifikasi tidak dikirim dengan benar.
  • Perubahan Daftar Kontrol Akses (ACL) tidak diizinkan untuk pengguna ini.

Kolom message menunjukkan error yang sebenarnya.

Berhasil berbagi, tetapi email notifikasi tidak dikirim dengan benar

Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, beri tahu pengguna (yang membagikan) bahwa ia tidak dapat berbagi karena email notifikasi tidak dapat dikirim ke alamat email tujuan. Tujuan pengguna harus memastikan bahwa mereka memiliki alamat email yang benar dan dapat menerima email.

Perubahan ACL tidak diizinkan untuk pengguna ini

Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki kesalahan ini, periksa setelan domain Google Workspace tempat file tersebut berada. Setelannya mungkin melarang berbagi di luar domain atau berbagi drive bersama mungkin tidak diizinkan.

Error 401

Error ini berarti permintaan tidak berisi token akses yang valid.

authError

Kesalahan ini terjadi ketika token akses yang Anda gunakan sudah tidak berlaku atau tidak valid. Error ini juga dapat disebabkan oleh tidak adanya otorisasi untuk cakupan yang diminta. Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, muat ulang token akses menggunakan token refresh yang berumur panjang. Jika gagal, arahkan pengguna melalui alur OAuth, seperti yang dijelaskan dalam Memilih Cakupan Google Drive API.

Error 403

Pesan error ini menunjukkan bahwa batas penggunaan telah terlampaui atau pengguna tidak memiliki hak istimewa yang benar. Untuk menentukan penyebabnya, evaluasi kolom reason dari JSON yang ditampilkan.

Untuk mengetahui informasi tentang batas Drive API, lihat Batas penggunaan. Untuk mengetahui informasi tentang folder Drive lihat Batas file dan folder.

activeItemCreationLimitExceeded

Error activeItemCreationLimitExceeded terjadi jika batas jumlah item yang dibuat per akun telah terlampaui. Setiap pengguna dapat memiliki maksimal 500 juta item yang dibuat oleh akun. Untuk informasi selengkapnya, lihat Item pengguna .

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "activeItemCreationLimitExceeded",
    "message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
   }
  ],
  "code": 403,
  "message": "This account has exceeded the creation limit of 500 million items. To create more items, permanently delete some items."
 }
}

Untuk memperbaiki error ini:

  1. Beri tahu pengguna bahwa Drive mencegah pembuatan akun lebih dari 500 juta item.

  2. Jika pengguna harus membuat item di akun yang sama, instruksikan mereka untuk menghapus beberapa objek secara permanen. Jika tidak, mereka dapat menggunakan akun lain yang sudah memenuhi persyaratan.

appNotAuthorizedToFile

Error ini terjadi saat aplikasi Anda tidak berada di ACL untuk file. Error ini mencegah pengguna membuka file dengan aplikasi Anda. Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, coba salah satu langkah berikut:

  • Buka pemilih Google Drive dan meminta pengguna untuk membuka file.
  • Minta pengguna untuk membuka file menggunakan menu konteks Buka dengan di Drive UI aplikasi Anda.
  • Gunakan metode files.get untuk periksa bidang isAppAuthorized di files untuk memverifikasi bahwa aplikasi yang membuat atau membuka file.

cannotModifyInheritedTeamDrivePermission

Error ini terjadi saat pengguna mencoba mengubah izin yang diwarisi dari item dalam drive bersama. Izin yang diwarisi tidak dapat dihapus dari item di drive bersama. Contoh JSON berikut adalah representasi dari error ini:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "cannotModifyInheritedTeamDrivePermission",
        "message": "Cannot update or delete an inherited permission on a shared drive item."
      }
    ],
    "code": 403,
    "message": "Cannot update or delete an inherited permission on a shared drive item."
  }
}

Untuk memperbaiki kesalahan ini, pengguna harus menyesuaikan izin akses item induk tempat mereka diwarisi. Untuk informasi selengkapnya, lihat Izin propagasi. Anda dapat juga mengambil permissions.permissionDetails resource untuk melihat apakah izin di item drive bersama ini diwariskan atau langsung diterapkan.

dailyLimitExceeded

Error ini terjadi ketika batas API untuk project Anda tercapai. Hal berikut Contoh JSON adalah representasi dari error ini:

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

Error ini muncul ketika pemilik aplikasi telah menetapkan batas kuota yang akan dibatasi penggunaan resource tertentu. Untuk memperbaiki kesalahan ini, hapus batas penggunaan untuk "Kueri per hari" kuota.

domainPolicy

Error ini terjadi ketika kebijakan untuk domain pengguna tidak mengizinkan akses ke Mengemudi dengan aplikasi Anda. Contoh JSON berikut adalah representasi error ini:

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

Untuk memperbaiki error ini:

  1. Beri tahu pengguna bahwa domain tidak mengizinkan aplikasi Anda mengakses file di Mengemudi.
  2. Instruksikan pengguna untuk menghubungi administrator domain untuk meminta akses bagi aplikasi Anda.

fileOwnerNotMemberOfTeamDrive

Error ini terjadi saat Anda mencoba memindahkan file ke drive bersama dan pemilik file bukanlah anggota. Contoh JSON berikut adalah representasi dari {i>error<i}:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "fileOwnerNotMemberOfTeamDrive",
        "message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
      }
    ],
    "code": 403,
    "message": "Cannot move a file into a shared drive as a writer when the owner of the file is not a member of that shared drive."
  }
}

Untuk memperbaiki error ini:

  1. Tambahkan anggota ke drive bersama dengan role=owner. Untuk informasi selengkapnya, lihat Berbagi file, folder, dan drive.

  2. Tambahkan file ke drive bersama. Untuk informasi selengkapnya, lihat Membuat dan mengisi folder.

fileWriterTeamDriveMoveInDisabled

Kesalahan ini terjadi ketika administrator domain belum mengizinkan pengguna dengan role=writer untuk memindahkan item ke drive bersama. Pengguna mencoba memindahkan item memiliki izin yang lebih sedikit dari yang diizinkan di drive bersama tujuan. Tujuan Contoh JSON berikut adalah representasi error ini:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "fileWriterTeamDriveMoveInDisabled",
        "message": "The domain administrator has not allowed writers to move items into a shared drive."
      }
    ],
    "code": 403,
    "message": "The domain administrator has not allowed writers to move items into a shared drive."
  }
}

Untuk memperbaiki error ini, gunakan akun pengguna administrator yang sama pada kedua sumber dan drive bersama tujuan.

insufficientFilePermissions

Kesalahan ini terjadi ketika pengguna tidak memiliki akses tulis ke file, dan aplikasi mencoba mengubah file. Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, minta pengguna untuk menghubungi pemilik file dan meminta akses edit. Anda juga dapat memeriksa tingkat akses pengguna dalam metadata yang diambil oleh metode files.get dan menampilkan UI hanya-baca jika izin tidak ada.

myDriveHierarchyDepthLimitExceeded

Error myDriveHierarchyDepthLimitExceeded terjadi jika batas untuk jumlah tingkat folder bertingkat telah terlampaui. {i>User's<i} Drive tidak dapat berisi lebih dari 100 tingkat folder bertingkat. Sebagai informasi selengkapnya, lihat Kedalaman folder .

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "myDriveHierarchyDepthLimitExceeded",
    "message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/drive/api/guides/handle-errors#nested-folder-levels."
   }
  ],
  "code": 403,
  "message": "Your My Drive can't contain more than 100 levels of folders. For details, see https://developers.google.com/drive/api/guides/handle-errors#nested-folder-levels."
 }
}

Untuk memperbaiki error ini:

  1. Beri tahu pengguna bahwa Drive tidak mengizinkan penempatan folder lebih dari 100 level.
  2. Jika pengguna harus membuat folder bersarang lain, instruksikan mereka untuk mengatur ulang folder induk yang dimaksud memiliki kedalaman kurang dari 100 tingkat atau menggunakan folder induk lain yang sudah memenuhi persyaratan.

numChildrenInNonRootLimitExceeded

Error ini terjadi ketika batas jumlah turunan folder (folder, file, dan pintasan) terlampaui. Ada batas 500.000 item untuk folder, file, dan pintasan langsung dalam sebuah folder. Item bertingkat di subfolder tidak mengurangi batas 500.000 item ini. Untuk mengetahui informasi selengkapnya tentang Batas folder Drive, lihat Batas folder di Google Drive.

Contoh JSON berikut adalah representasi dari error ini:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "numChildrenInNonRootLimitExceeded",
    "message": "The limit for this folder's number of children (files and folders) has been exceeded."
   }
  ],
  "code": 403,
  "message": "The limit for this folder's number of children (files and folders) has been exceeded."
 }
}

Untuk memperbaiki error ini, coba salah satu langkah berikut:

  • Beri tahu pengguna bahwa Drive mencegah folder yang berisi lebih dari 500.000 item.
  • Jika pengguna harus menambahkan lebih banyak item ke folder lengkap, instruksikan mereka untuk atur ulang folder agar berisi kurang dari 500.000 item atau gunakan yang sudah berisi lebih sedikit item.

rateLimitExceeded

Error ini terjadi saat batas kapasitas project telah tercapai. Batasan ini bervariasi bergantung pada jenis permintaan. Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, coba salah satu langkah berikut:

sharingRateLimitExceeded

Error ini terjadi saat pengguna mencapai batas berbagi dan sering kali ditautkan dengan batas jumlah email. Contoh JSON berikut adalah representasi dari {i>error<i}:

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

Untuk memperbaiki error ini:

  1. Jangan kirim email saat berbagi file dalam jumlah besar.
  2. Jika satu pengguna membuat banyak permintaan atas nama banyak pengguna dari untuk menggunakan akun Google Workspace, pertimbangkan akun layanan dengan seluruh domain delegasi menggunakan quotaUser .

storageQuotaExceeded

Error ini terjadi saat pengguna mencapai batas penyimpanan. Hal berikut Contoh JSON adalah representasi dari error ini:

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

Untuk memperbaiki error ini:

  1. Tinjau batas penyimpanan akun Drive Anda. Untuk selengkapnya informasi Anda, lihat penyimpanan dan upload Google Workspace batasan ini.

  2. Mengelola file di Google Drive Google Cloud Storage.

  3. Beli lebih banyak Google Google Cloud Storage.

teamDriveFileLimitExceeded

Error ini terjadi ketika pengguna mencoba untuk melebihi batas item yang ketat pada {i>drive bersama<i}. Setiap folder di drive bersama pengguna memiliki batas 500.000 item, termasuk file, folder, dan pintasan. Batas ini didasarkan pada jumlah item, bukan penggunaan penyimpanan. Untuk informasi selengkapnya, lihat Batas drive bersama di Google Drive.

Contoh JSON berikut adalah representasi dari error ini:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDriveFileLimitExceeded",
        "message": "The file limit for this shared drive has been exceeded."
      }
    ],
    "code": 403,
    "message": "The file limit for this shared drive has been exceeded."
  }
}

Untuk memperbaiki error ini, kurangi jumlah item di drive bersama. Drive bersama yang memiliki terlalu banyak file mungkin akan sulit untuk diatur dan dicari.

teamDriveHierarchyTooDeep

Error teamDriveHierarchyTooDeep terjadi jika batas jumlah tingkat folder bertingkat drive bersama telah terlampaui. Drive bersama pengguna tidak dapat berisi lebih dari 100 tingkat folder {i>nested<i}. Untuk informasi selengkapnya, lihat Batas kedalaman folder.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "teamDriveHierarchyTooDeep",
    "message": "The shared drive hierarchy depth will exceed the limit."
   }
  ],
  "code": 403,
  "message": "The shared drive hierarchy depth will exceed the limit."
 }
}

Untuk memperbaiki error ini:

  1. Beri tahu pengguna bahwa drive bersama mencegah folder ditempatkan lebih dari 100 level.
  2. Jika pengguna harus membuat folder bersarang lain, instruksikan mereka untuk mengatur ulang folder induk yang dimaksud memiliki kedalaman kurang dari 100 tingkat atau menggunakan folder induk lain yang sudah memenuhi persyaratan.

teamDriveMembershipRequired

Error ini terjadi saat pengguna mencoba mengakses drive bersama tempat mereka bukan anggota. Contoh JSON berikut adalah representasi dari error ini:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDriveMembershipRequired",
        "message": "The attempted action requires shared drive membership."
      }
    ],
    "code": 403,
    "message": "The attempted action requires shared drive membership."
  }
}

Untuk memperbaiki error ini, coba salah satu langkah berikut:

  1. Minta pengelola drive bersama untuk menambahkan Anda ke drive bersama izin untuk tindakan yang harus Anda lakukan.

  2. Tinjau Peran dan izin untuk mempelajari siapa saja yang dapat mengakses dan mengelola {i>shared drive<i} secara bersama-sama. Informasi tambahan tentang tingkat akses juga dapat ditemukan di Membuat Google Drive.

teamDrivesFolderMoveInNotSupported

Kesalahan ini terjadi ketika pengguna mencoba memindahkan folder dari Drive ke drive bersama. Contoh JSON berikut adalah representasi dari error ini:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDrivesFolderMoveInNotSupported",
        "message": "Moving folders into shared drives is not supported."
      }
    ],
    "code": 403,
    "message": "Moving folders into shared drives is not supported."
  }
}

Untuk memperbaiki error ini, coba salah satu langkah berikut:

  • Pindahkan setiap item dari folder ke drive bersama menggunakan API Drive. Setel parameter supportsAllDrives=true untuk menunjukkan dukungan untuk Drive Saya dan drive bersama.

  • Jika Anda harus memindahkan folder ke drive bersama, gunakan UI Drive. Untuk mengetahui informasi selengkapnya, lihat Memindahkan folder ke folder bersama drive sebagai admin.

teamDrivesParentLimit

Error ini terjadi saat pengguna mencoba menambahkan lebih dari satu induk ke item di {i>drive<i} bersama. Contoh JSON berikut adalah representasi dari error ini:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "teamDrivesParentLimit",
        "message": "A shared drive item must have exactly one parent."
      }
    ],
    "code": 403,
    "message": "A shared drive item must have exactly one parent."
  }
}

Untuk memperbaiki error ini, gunakan pintasan Drive untuk menambahkan beberapa link ke . Meskipun {i>shortcut<i} hanya dapat memiliki satu induk, sebuah file {i>shortcut<i} dapat disalin ke lokasi tambahan. Untuk informasi selengkapnya, lihat Membuat pintasan ke file Drive.

UrlLeaseLimitExceeded

Error ini terjadi saat mencoba menyimpan data game Google Play melalui aplikasi. Contoh JSON berikut adalah representasi dari error ini:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "UrlLeaseLimitExceeded",
    "message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
   }
  ],
  "code": 403,
  "message": "Too many pending uploads for this snapshot. Please finish or cancel some before creating more."
 }
}

Untuk memperbaiki error ini, selesaikan atau batalkan upload snapshot sebelum membuatnya banyak lagi.

userRateLimitExceeded

Error ini terjadi ketika batas per pengguna telah tercapai. Mungkin ini adalah batas dari Konsol Google Cloud atau batas dari Drive backend. Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, coba salah satu langkah berikut:

Untuk mengetahui informasi tentang batas Drive API, lihat Batas penggunaan.

Error 404

Error ini menunjukkan bahwa resource yang diminta tidak dapat diakses atau tidak ada.

notFound

Error ini terjadi ketika pengguna tidak memiliki akses baca ke file, atau file tidak ada. Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini:

  1. Jika file berada di drive bersama, dan Anda menggunakan files.get, pastikan metode Parameter kueri supportsAllDrives ditetapkan ke true.
  2. Beri tahu pengguna bahwa mereka tidak memiliki akses baca ke file atau file tidak ada.
  3. Instruksikan pengguna untuk menghubungi pemilik file dan meminta izin ke .

Error 429

Error ini menunjukkan bahwa terlalu banyak permintaan yang dikirim ke API terlalu cepat.

rateLimitExceeded

Error ini terjadi ketika pengguna telah mengirimkan terlalu banyak permintaan dalam satu paket lama waktu. Contoh JSON berikut adalah representasi dari error ini:

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

Untuk memperbaiki error ini, gunakan eksponensial backoff untuk mencoba kembali permintaan tersebut.

500, 502, 503, 504 error

Error ini terjadi ketika muncul error server yang tidak terduga saat memproses permintaan. Berbagai masalah dapat menyebabkan error ini, termasuk waktu permintaan tumpang-tindih dengan permintaan lain atau permintaan untuk tindakan yang tidak didukung, seperti mencoba memperbarui izin untuk satu halaman di Google Sites seluruh situs.

Berikut adalah daftar error 5xx:

  • Error backend 500
  • 502 Gateway Buruk
  • 503 Layanan Tidak Tersedia
  • 504 Waktu Tunggu Gateway

Untuk memperbaiki error ini, gunakan eksponensial backoff untuk mencoba kembali permintaan tersebut.