Mengatasi error

Gmail API menampilkan dua tingkat informasi error:

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

Aplikasi Gmail Anda harus menangkap dan menangani semua error yang mungkin terjadi saat menggunakan REST API. Panduan ini memberikan petunjuk tentang cara mengatasi error Gmail 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 error klien dalam permintaan.
`401 - Unauthorized`	Permintaan berisi kredensial yang tidak valid.
`403 - Forbidden`	Permintaan 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 memiliki error, sering kali karena parameter wajib diisi tidak ada.

`badRequest`

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

Kolom atau parameter yang wajib diisi belum diberikan.
Nilai yang diberikan atau kombinasi kolom yang diberikan tidak valid.
Lampiran tidak valid.

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.

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 otorisasi yang tidak ada 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, refresh token akses menggunakan token refresh yang berlaku lama. Jika Anda menggunakan library klien, library tersebut akan otomatis menangani pemuatan ulang token. Jika gagal, arahkan pengguna melalui alur OAuth, seperti yang dijelaskan dalam Mempelajari autentikasi dan otorisasi.

Untuk mengetahui informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Error 403

Error ini terjadi saat Anda melampaui batas penggunaan atau pengguna tidak memiliki hak istimewa yang benar. Untuk mengetahui penyebabnya, evaluasi kolom reason dari JSON yang ditampilkan. Error ini terjadi dalam situasi berikut:

Aplikasi Anda tidak dapat digunakan dalam domain pengguna yang diautentikasi.
Batas harian terlampaui.
Batas kapasitas pengguna terlampaui.
Batas kapasitas project telah terlampaui.

Untuk mengetahui informasi selengkapnya, lihat Batas penggunaan.

`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, tingkatkan kuota di project Google Cloud. Untuk mengetahui informasi selengkapnya, lihat Mengelola batas kuota.

`domainPolicy`

Error ini terjadi saat kebijakan untuk domain pengguna tidak mengizinkan aplikasi Anda mengakses Gmail. JSON berikut adalah representasi error ini:

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

Untuk memperbaiki error ini, coba langkah-langkah berikut:

Memberi tahu pengguna bahwa domain tidak mengizinkan aplikasi Anda mengakses Gmail.
Mengarahkan pengguna untuk menghubungi administrator domain mereka guna meminta akses untuk aplikasi Anda.

`rateLimitExceeded`

Error ini menunjukkan bahwa pengguna telah mencapai kecepatan permintaan maksimum Gmail API. 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 langkah-langkah berikut:

Minta penambahan kuota.
Gunakan backoff eksponensial untuk mencoba lagi permintaan.

`userRateLimitExceeded`

Error ini terjadi saat batas per pengguna telah tercapai. 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 optimalkan kode aplikasi Anda untuk membuat lebih sedikit permintaan atau gunakan backoff eksponensial untuk mencoba ulang permintaan.

Error 429

Error 429 "Terlalu banyak permintaan" dapat terjadi karena batas harian per pengguna (termasuk batas pengiriman email), batas bandwidth, atau batas permintaan serentak per pengguna. Berikut adalah informasi tentang setiap batas. Namun, setiap batas dapat diselesaikan dengan mencoba lagi permintaan yang gagal atau dengan membagi pemrosesan di beberapa akun Gmail.

Batas per pengguna tidak dapat ditingkatkan karena alasan apa pun. Untuk mengetahui informasi selengkapnya tentang batas, lihat Batas penggunaan.

Batas pengiriman email

Gmail API menerapkan batas pengiriman email harian standar. Batas ini berbeda untuk pengguna Google Workspace berbayar dan pengguna uji coba gmail.com. Untuk batas ini, lihat Batas pengiriman Gmail di Google Workspace.

Batas ini berlaku per pengguna dan dibagikan oleh semua klien pengguna, baik klien API, klien web atau bawaan, maupun MSA SMTP. Jika batas ini terlampaui, error HTTP 429 "Terlalu banyak permintaan: Batas frekuensi pengguna terlampaui (Pengiriman email)" akan ditampilkan dengan waktu untuk mencoba lagi. Batas harian yang terlampaui dapat menyebabkan error ini selama beberapa jam sebelum permintaan diterima.

Pipeline pengiriman email bersifat kompleks: setelah pengguna melampaui kuotanya, mungkin ada penundaan selama beberapa menit sebelum API mulai menampilkan respons error 429. Anda tidak dapat mengasumsikan bahwa respons 200 berarti email berhasil dikirim.

Batas bandwidth

API memiliki batas bandwidth upload dan download per pengguna yang sama dengan, tetapi terpisah dari, IMAP. Batas ini digunakan bersama oleh semua klien Gmail API untuk pengguna.

Batas ini biasanya hanya tercapai dalam situasi yang tidak biasa atau penyalahgunaan. Jika batas ini terlampaui, error HTTP 429 "Too many requests: User-rate limit exceeded" akan ditampilkan dengan waktu untuk mencoba lagi. Batas harian yang terlampaui dapat menyebabkan error ini selama beberapa jam sebelum permintaan diterima.

Permintaan serentak

Gmail API menerapkan batas permintaan serentak per pengguna (selain batas kecepatan per pengguna). Batas ini digunakan bersama oleh semua klien Gmail API yang mengakses pengguna dan memastikan bahwa tidak ada klien API yang membebani kotak surat pengguna Gmail atau server backend-nya.

Membuat banyak permintaan paralel untuk satu pengguna atau mengirim batch dengan sejumlah besar permintaan dapat memicu error ini. Sejumlah besar klien API independen yang mengakses kotak surat pengguna Gmail secara bersamaan juga dapat memicu error ini. Jika batas ini terlampaui, error HTTP 429 "Too many requests: Too many concurrent requests for user" akan ditampilkan.

Error 500, 502, 503, 504

Error ini terjadi saat terjadi 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:

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

backendError

Error ini terjadi saat terjadi error yang tidak terduga saat memproses permintaan. Contoh JSON berikut adalah representasi dari error ini:

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

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

Mencoba lagi permintaan yang gagal untuk mengatasi error

Anda dapat mencoba kembali permintaan yang gagal secara berkala dengan menambah lamanya penundaan antara setiap permintaan yang gagal untuk menangani error terkait batas frekuensi, volume jaringan, atau waktu respons. Misalnya, Anda dapat mencoba lagi permintaan yang gagal setelah satu detik, lalu setelah dua detik, dan kemudian setelah empat detik. Metode ini disebut backoff eksponensial, dan digunakan untuk meningkatkan penggunaan bandwidth dan memaksimalkan throughput permintaan dalam lingkungan serentak.

Mulai periode percobaan ulang setidaknya satu detik setelah error.

Mengelola batas kuota

Untuk melihat atau mengubah batas penggunaan untuk project Anda atau meminta penambahan kuota, lakukan hal berikut ini:

Jika Anda belum memiliki akun penagihan untuk project, buat akun penagihan.
Buka halaman API yang Diaktifkan dari library API di Konsol API, lalu pilih API dari daftar.
Untuk melihat dan mengubah setelan terkait kuota, pilih Kuota. Untuk melihat statistik penggunaan, pilih Penggunaan.

Untuk mengetahui informasi selengkapnya, lihat Melihat dan mengelola kuota.

Permintaan batch

Penggunaan permintaan batch dianjurkan; namun, ukuran batch yang lebih besar cenderung memicu pembatasan kecepatan. Mengirim batch yang lebih besar dari 50 permintaan tidak disarankan. Untuk mengetahui informasi tentang cara mengelompokkan permintaan, lihat Permintaan batch.