Google Drive API menampilkan dua tingkat informasi error:
- Kode error dan pesan header HTTP.
- 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 memberikan petunjuk tentang cara menyelesaikan 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 diterima dan dipahami, tetapi pengguna tidak memiliki izin untuk menjalankan permintaan tersebut. |
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 tidak terduga saat memproses permintaan. |
Error 400
Error ini berarti permintaan tidak dapat diterima, sering kali karena parameter yang diperlukan tidak ada.
badRequest
Error ini dapat terjadi dari salah satu masalah berikut dalam kode Anda:
- Kolom atau parameter yang diperlukan 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 dalam grafik direktori.
Contoh JSON berikut adalah representasi 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. Error 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 sebenarnya.
Berbagi berhasil, tetapi email notifikasi tidak terkirim dengan benar
Contoh JSON berikut adalah representasi 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 (pembagi) bahwa mereka tidak dapat berbagi karena email notifikasi tidak dapat dikirim ke alamat email 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 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 berada. Setelan tersebut 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
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 error ini:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Untuk memperbaiki error ini, perbarui token akses menggunakan token pembaruan yang berumur panjang. Jika gagal, arahkan pengguna melalui alur OAuth, seperti yang dijelaskan dalam Memilih cakupan Google Drive API.
fileNotDownloadable
Error ini terjadi saat Anda mencoba menggunakan metode revisions.get
dengan
parameter URL alt=media
pada dokumen Google Workspace. Contoh JSON berikut adalah representasi error ini:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "fileNotDownloadable",
"message": "Only files with binary content can be downloaded. Use Export with Docs Editors files."
}
],
"code": 403,
"message": "Only files with binary content can be downloaded. Use Export with Docs Editors files."
}
}
Untuk memperbaiki error ini, coba salah satu hal berikut:
- Hapus parameter URL
alt=media
jika Anda ingin melihat metadata revisi tertentu, seperti mimetype. - Gunakan metode
files.export
untuk mengekspor konten byte dokumen Google Workspace. Untuk mengetahui informasi selengkapnya, lihat Mengekspor konten dokumen Google Workspace.
Error 403
Error ini berarti batas penggunaan telah terlampaui atau pengguna tidak memiliki
hak istimewa yang benar. Untuk menentukan penyebabnya, evaluasi kolom reason
dari
JSON yang ditampilkan.
Untuk informasi tentang batas Drive API, lihat Batas penggunaan. Untuk 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 maksimal 500
juta item yang dibuat oleh 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:
Beri tahu pengguna bahwa Drive mencegah akun membuat lebih dari 500 juta item.
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. Error ini mencegah pengguna membuka file dengan aplikasi Anda. Contoh JSON berikut adalah representasi 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 hal berikut:
- Buka pemilih 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 kolomisAppAuthorized
di resourcefiles
untuk memverifikasi bahwa aplikasi Anda membuat atau membuka file.
cannotModifyInheritedTeamDrivePermission
Error ini terjadi saat pengguna mencoba mengubah izin yang diwarisi dari item dalam drive bersama. Izin yang diwariskan tidak dapat dihapus dari item di drive bersama. Contoh JSON berikut adalah representasi 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 pada item induk langsung atau tidak langsung
yang diwarisi. Untuk informasi selengkapnya, lihat
Penyebaran
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 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 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:
- Beri tahu pengguna bahwa domain tidak mengizinkan aplikasi Anda mengakses file di Drive.
- Minta pengguna untuk menghubungi administrator domain guna meminta akses untuk aplikasi Anda.
fileOwnerNotMemberOfTeamDrive
Error ini terjadi saat mencoba memindahkan file ke drive bersama dan pemilik file 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:
Tambahkan anggota ke drive bersama dengan
role=owner
. Untuk informasi selengkapnya, lihat Berbagi file, folder, dan drive.Tambahkan file ke drive bersama. Untuk mengetahui informasi selengkapnya, lihat Membuat dan mengisi folder.
fileWriterTeamDriveMoveInDisabled
Error ini terjadi jika administrator domain belum mengizinkan pengguna dengan
role=writer
untuk memindahkan item ke drive bersama. Pengguna yang mencoba memindahkan
item memiliki lebih sedikit izin daripada 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. 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 oleh
metode files.get
dan menampilkan
UI hanya baca jika izin tidak ada.
myDriveHierarchyDepthLimitExceeded
Error myDriveHierarchyDepthLimitExceeded
terjadi saat batas jumlah tingkat folder bertingkat 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:
- Beri tahu pengguna bahwa Drive mencegah penempatan folder lebih dari 100 tingkat.
- Jika pengguna harus membuat folder bertingkat lain, minta mereka untuk mengatur ulang folder induk yang diinginkan agar kedalamannya kurang dari 100 tingkat atau menggunakan folder induk lain yang sudah memenuhi persyaratan.
numChildrenInNonRootLimitExceeded
Error ini terjadi jika batas jumlah turunan folder (folder, file, dan pintasan) telah terlampaui. Ada batas 500.000 item untuk folder, file, dan pintasan langsung di folder. Item bertingkat dalam subfolder tidak dihitung dalam batas 500.000 item ini. Untuk mengetahui informasi selengkapnya tentang batas folder Drive, lihat Batas folder di Google Drive.
Contoh JSON berikut adalah representasi 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 hal berikut:
- Beri tahu pengguna bahwa Drive mencegah folder dengan lebih dari 500.000 item.
- Jika pengguna harus menambahkan lebih banyak item ke folder yang penuh, minta mereka untuk mengatur ulang folder 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 hal berikut:
- Naikkan kuota per pengguna di project Google Cloud. Untuk mengetahui informasi selengkapnya, minta penambahan kuota.
- Permintaan batch untuk memaketkan beberapa panggilan API menjadi satu permintaan HTTP.
- Gunakan backoff eksponensial untuk mencoba ulang permintaan.
sharingRateLimitExceeded
Error ini terjadi saat pengguna mencapai batas berbagi dan sering dikaitkan 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:
- Jangan mengirim email saat berbagi file dalam jumlah besar.
- Jika satu pengguna membuat banyak permintaan atas nama banyak pengguna akun Google Workspace, pertimbangkan akun layanan dengan delegasi seluruh domain menggunakan parameter
quotaUser
.
storageQuotaExceeded
Error ini terjadi saat pengguna mencapai batas penyimpanannya. Contoh JSON berikut adalah representasi 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:
Tinjau batas penyimpanan akun Drive Anda. Untuk informasi selengkapnya, lihat Batas penyimpanan dan upload Google Workspace.
teamDriveFileLimitExceeded
Error ini terjadi saat pengguna mencoba melampaui batas item yang ketat di drive bersama. 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 mengetahui informasi selengkapnya, lihat Batas drive bersama di Google Drive.
Contoh JSON berikut adalah representasi 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 berisi terlalu banyak file mungkin sulit untuk diatur dan ditelusuri.
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 bertingkat. 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:
- Beri tahu pengguna bahwa drive bersama mencegah penempatan folder lebih dari 100 tingkat.
- Jika pengguna harus membuat folder bertingkat lain, minta mereka untuk mengatur ulang folder induk yang diinginkan agar kedalamannya kurang dari 100 tingkat atau menggunakan folder induk lain yang sudah memenuhi persyaratan.
teamDriveMembershipRequired
Error ini terjadi saat pengguna mencoba mengakses drive bersama yang bukan merupakan anggotanya. Contoh JSON berikut adalah representasi 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 hal berikut:
Minta pengelola drive bersama untuk menambahkan Anda dengan izin yang sesuai untuk tindakan yang harus Anda lakukan.
Tinjau Peran dan izin Drive untuk mempelajari 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 hal berikut:
Pindahkan setiap item dari folder ke drive bersama menggunakan Drive API. Tetapkan parameter
supportsAllDrives=true
untuk menunjukkan dukungan Drive Saya dan drive bersama.Jika Anda harus memindahkan folder ke drive bersama, gunakan UI Drive. Untuk 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 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 dikopy 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 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 untuk snapshot sebelum membuat snapshot lainnya.
userRateLimitExceeded
Error ini terjadi saat batas per pengguna telah tercapai. Batas ini mungkin berupa batas dari konsol Google Cloud atau batas dari backend Drive. Contoh JSON berikut adalah representasi 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 hal berikut:
Naikkan kuota per pengguna di project Google Cloud. Untuk mengetahui informasi selengkapnya, minta penambahan kuota.
Jika satu pengguna membuat banyak permintaan atas nama banyak pengguna akun Google Workspace, pertimbangkan akun layanan dengan delegasi seluruh domain menggunakan parameter
quotaUser
.Gunakan backoff eksponensial untuk mencoba ulang permintaan.
Untuk informasi tentang batas Drive API, lihat Batas penggunaan.
Error 404
Error ini berarti bahwa resource yang diminta tidak dapat diakses atau tidak ada.
notFound
Error ini terjadi saat pengguna tidak memiliki akses baca ke file, atau file tidak ada. Contoh JSON berikut adalah representasi error ini:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "File not found {fileId}"
}
],
"code": 404,
"message": "File not found: {fileId}"
}
}
Untuk memperbaiki error ini:
- Jika file berada di drive bersama, dan Anda menggunakan metode
files.get
, pastikan parameter kuerisupportsAllDrives
ditetapkan ketrue
. - Beri tahu pengguna bahwa mereka tidak memiliki akses baca ke file atau file tersebut tidak ada.
- Minta pengguna untuk menghubungi pemilik file dan meminta izin ke file.
Error 429
Error ini berarti terlalu banyak permintaan yang dikirim ke API terlalu cepat.
rateLimitExceeded
Error ini terjadi saat pengguna telah mengirim terlalu banyak permintaan dalam jumlah waktu tertentu. Contoh JSON berikut adalah representasi 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 ulang permintaan.
Error 500, 502, 503, 504
Error ini terjadi saat error server yang tidak terduga muncul 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 ulang permintaan.