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 error.

Aplikasi Google Drive harus menangkap dan menangani semua error yang mungkin terjadi saat menggunakan REST API. Panduan ini berisi petunjuk 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 tak terduga saat memproses permintaan.

Error 400

Error ini berarti bahwa permintaan tidak dapat diterima, sering kali karena tidak adanya parameter yang diperlukan.

badRequest

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

  • Kolom atau parameter yang wajib diisi belum diberikan.
  • Nilai yang diberikan atau kombinasi kolom yang disediakan tidak valid.
  • Anda mencoba menambahkan orang tua duplikat ke file Drive.
  • Anda mencoba menambahkan induk yang akan membuat siklus dalam 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 mengetahui penyebabnya, evaluasi kolom reason dari JSON yang ditampilkan. Error ini paling sering terjadi karena:

  • Berhasil berbagi, 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 mereka tidak dapat berbagi karena email notifikasi tidak dapat dikirim ke alamat email tujuan. Pengguna harus memastikan bahwa dia 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 error ini, periksa setelan berbagi domain Google Workspace tempat file tersebut berada. Setelan ini mungkin melarang berbagi di luar domain, atau berbagi drive bersama mungkin tidak diizinkan.

Error 401

Error ini menunjukkan bahwa permintaan tidak berisi token akses yang valid.

authError

Error ini terjadi jika 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 memiliki masa aktif lama. Jika gagal, arahkan pengguna melalui alur OAuth, seperti yang dijelaskan dalam Memilih cakupan Google Drive API.

Error 403

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

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

activeItemCreationLimitExceeded

Error activeItemCreationLimitExceeded terjadi saat batas jumlah item yang dibuat per akun terlampaui. Setiap pengguna dapat memiliki hingga 500 juta item yang dibuat oleh satu akun. Untuk informasi selengkapnya, lihat Batas 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 akun membuat lebih dari 500 juta item.

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

appNotAuthorizedToFile

Error ini terjadi jika aplikasi Anda tidak ada di ACL untuk file tersebut. 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 alat pilih Google Drive dan minta pengguna untuk membuka file.
  • Minta pengguna untuk membuka file menggunakan menu konteks Buka dengan di UI Drive aplikasi Anda.
  • Gunakan metode files.get untuk memeriksa kolom isAppAuthorized di resource files untuk memverifikasi bahwa aplikasi Anda membuat atau membuka file.

cannotModifyInheritedTeamDrivePermission

Error ini terjadi saat pengguna mencoba mengubah izin yang diwarisi sebuah 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 error ini, pengguna harus menyesuaikan izin item induk langsung atau tidak langsung tempat item induk tersebut diwarisi. Untuk informasi selengkapnya, lihat Penerapan izin. Anda juga dapat mengambil resource permissions.permissionDetails untuk melihat apakah izin pada item drive bersama ini diwariskan atau diterapkan secara langsung.

dailyLimitExceeded

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

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

Error ini muncul saat pemilik aplikasi telah menetapkan batas kuota untuk membatasi penggunaan resource tertentu. Untuk memperbaiki error ini, hapus batas penggunaan untuk kuota "Kueri per hari".

domainPolicy

Error ini terjadi jika kebijakan untuk domain pengguna tidak mengizinkan akses ke Drive oleh aplikasi Anda. Contoh JSON berikut adalah representasi dari 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 Drive.
  2. Minta pengguna menghubungi administrator domain untuk meminta akses untuk aplikasi Anda.

fileOwnerNotMemberOfTeamDrive

Error ini terjadi saat mencoba memindahkan file ke drive bersama dan pemilik filenya bukan anggota. Contoh JSON berikut adalah representasi error ini:

{
  "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 mengetahui informasi selengkapnya, lihat Berbagi file, folder, dan drive.

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

fileWriterTeamDriveMoveInDisabled

Error ini terjadi saat administrator domain tidak mengizinkan pengguna dengan role=writer untuk memindahkan item ke drive bersama. Pengguna yang mencoba memindahkan item memiliki izin yang lebih sedikit dari yang diizinkan di drive bersama 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 di drive bersama sumber dan tujuan.

insufficientFilePermissions

Error ini terjadi saat pengguna tidak memiliki akses tulis ke file, dan aplikasi Anda mencoba mengubah file tersebut. Contoh JSON berikut adalah representasi 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 dengan metode files.get dan menampilkan UI hanya baca jika izin tidak ada.

myDriveHierarchyDepthLimitExceeded

Error myDriveHierarchyDepthLimitExceeded terjadi saat batas jumlah tingkat folder bertingkat telah terlampaui. Drive Saya milik pengguna tidak dapat berisi lebih dari 100 tingkat folder bertingkat. Untuk mengetahui informasi selengkapnya, lihat Batas 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 mencegah penempatan folder lebih dari 100 tingkat.
  2. Jika pengguna harus membuat folder bertingkat lainnya, minta mereka mengatur ulang folder induk yang dimaksud agar memiliki kedalaman kurang dari 100 level atau gunakan folder induk lain yang sudah memenuhi persyaratan.

numChildrenInNonRootLimitExceeded

Error ini terjadi saat batas jumlah turunan folder (folder, file, dan pintasan) telah terlampaui. Ada batas 500.000 item untuk folder, file, dan pintasan langsung di dalam folder. Item yang disusun bertingkat dalam subfolder tidak diperhitungkan terhadap batas 500.000 item ini. Untuk 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, minta mereka mengatur ulang folder tersebut agar berisi kurang dari 500.000 item atau menggunakan folder serupa yang sudah berisi lebih sedikit item.

rateLimitExceeded

Error ini terjadi saat batas kapasitas project telah tercapai. Batas ini bervariasi bergantung pada jenis permintaan. Contoh JSON berikut adalah representasi 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 ditautkan dengan batas email. Contoh JSON berikut adalah representasi error ini:

{
 "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 mengirim email saat berbagi file dalam jumlah besar.
  2. Jika satu pengguna membuat banyak permintaan atas nama banyak pengguna di akun Google Workspace, pertimbangkan akun layanan dengan delegasi seluruh domain menggunakan parameter quotaUser.

storageQuotaExceeded

Error ini terjadi saat pengguna mencapai batas penyimpanan. Contoh JSON berikut 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 mengetahui informasi selengkapnya, lihat Batas penyimpanan dan upload Google Workspace.

  2. Mengelola file di penyimpanan Google Drive Anda.

  3. Beli lebih banyak penyimpanan Google.

teamDriveFileLimitExceeded

Error ini terjadi saat pengguna mencoba melebihi batas item yang ketat di drive bersama. Setiap folder di drive bersama pengguna memiliki batas 400.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 dengan terlalu banyak file mungkin akan sulit untuk diatur dan ditelusuri.

teamDriveMembershipRequired

Error ini terjadi saat pengguna mencoba mengakses drive bersama tempat mereka bukan anggotanya. 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 dengan izin yang sesuai untuk tindakan yang harus Anda lakukan.

  2. Tinjau Peran dan izin Drive untuk mengetahui siapa yang dapat mengakses dan mengelola drive bersama. Informasi tambahan tentang tingkat akses juga dapat ditemukan di Membuat drive bersama.

teamDrivesFolderMoveInNotSupported

Error ini terjadi saat pengguna mencoba memindahkan folder dari Drive Saya ke drive bersama. Contoh JSON berikut adalah representasi 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 Drive API. Tetapkan parameter supportsAllDrives=true untuk menunjukkan dukungan dari Drive Saya dan drive bersama.

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

teamDrivesParentLimit

Error ini terjadi saat pengguna mencoba menambahkan lebih dari satu induk ke item di drive 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 file. Meskipun pintasan hanya dapat memiliki satu induk, file pintasan dapat disalin ke lokasi tambahan. Untuk mengetahui informasi selengkapnya, lihat Membuat pintasan ke file Drive.

UrlLeaseLimitExceeded

Error ini terjadi saat mencoba menyimpan data game Google Play melalui aplikasi Anda. 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 membuat snapshot lainnya.

userRateLimitExceeded

Error ini terjadi saat batas per pengguna telah tercapai. Hal ini mungkin berupa batas dari konsol Google Cloud atau batas dari backend Drive. 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:

  • Naikkan kuota per pengguna di project Google Cloud. Untuk mengetahui informasi selengkapnya, minta penambahan kuota.

Untuk 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 saat pengguna tidak memiliki akses baca ke file, atau file tersebut 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 metode files.get, pastikan parameter kueri supportsAllDrives ditetapkan ke true.
  2. Beri tahu pengguna bahwa mereka tidak memiliki akses baca ke file atau file tersebut tidak ada.
  3. Minta pengguna untuk menghubungi pemilik file dan meminta izin ke file.

Error 429

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

rateLimitExceeded

Error ini terjadi jika pengguna telah mengirim terlalu banyak permintaan dalam jangka waktu tertentu. 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 backoff eksponensial untuk mencoba lagi permintaan tersebut.

Kesalahan 500, 502, 503, 504

Error ini terjadi saat muncul error server yang tidak terduga saat memproses permintaan. Berbagai masalah dapat menyebabkan error ini, termasuk waktu permintaan yang tumpang-tindih dengan permintaan lain atau permintaan untuk tindakan yang tidak didukung, seperti mencoba memperbarui izin untuk satu halaman di Google Sites, bukan 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 backoff eksponensial untuk mencoba lagi permintaan tersebut.