Mengatasi error

Gmail API menampilkan dua tingkat informasi error:

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

Aplikasi Gmail harus menangkap dan menangani semua error yang mungkin terjadi saat menggunakan REST API. Panduan ini memberikan petunjuk tentang cara menyelesaikan error API tertentu.

Menyelesaikan error 400: Permintaan tidak valid

Error ini mungkin disebabkan oleh error berikut dalam kode Anda:

  • Kolom atau parameter yang diperlukan belum diberikan.
  • Nilai yang diberikan atau kombinasi kolom yang diberikan tidak valid.
  • Lampiran tidak valid.

Berikut adalah contoh representasi JSON 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.

Mengatasi error 401: Kredensial tidak valid

Error 401 menunjukkan bahwa token akses yang Anda gunakan sudah tidak berlaku atau tidak valid. Error ini juga dapat disebabkan oleh tidak adanya otorisasi untuk cakupan yang diminta. Berikut adalah representasi JSON untuk 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 Anda menggunakan library klien, library tersebut akan otomatis menangani pembaruan token. Jika gagal, arahkan pengguna melalui alur OAuth, seperti yang dijelaskan dalam Memberi Otorisasi Aplikasi dengan Gmail.

Untuk informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Memecahkan error 403: Melebihi batas penggunaan

Error 403 terjadi saat batas penggunaan telah terlampaui atau pengguna tidak memiliki hak istimewa yang benar. Untuk menentukan jenis error tertentu, evaluasi kolom reason dari JSON yang ditampilkan. Error ini terjadi untuk situasi berikut:

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

Untuk informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Menyelesaikan error 403: Batas harian terlampaui

Error dailyLimitExceeded menunjukkan bahwa batas API courtesy untuk project Anda telah tercapai. Berikut adalah representasi JSON untuk error ini:

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

Untuk memperbaiki error ini:

  1. Buka Konsol API Google
  2. Pilih project Anda.
  3. Klik tab Kuota
  4. Minta kuota tambahan. Untuk mengetahui informasi selengkapnya, lihat Meminta kuota tambahan.

Untuk informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Menyelesaikan error 403: Batas kapasitas pengguna terlampaui

Error userRateLimitExceeded menunjukkan bahwa batas per pengguna telah tercapai. Berikut adalah representasi JSON 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 agar membuat lebih sedikit permintaan atau coba ulang permintaan. Untuk informasi tentang cara mencoba kembali permintaan, lihat Mencoba lagi permintaan yang gagal untuk mengatasi error.

Untuk informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Mengatasi error 403: Batas kapasitas terlampaui

Error rateLimitExceeded menunjukkan bahwa pengguna telah mencapai tingkat permintaan maksimum Gmail API. Batas ini bervariasi bergantung pada jenis permintaan. Berikut adalah representasi JSON untuk error ini:

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

Untuk memperbaiki error ini, coba lagi permintaan yang gagal.

Untuk informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Menyelesaikan error 403: Aplikasi dengan ID {appId} tidak dapat digunakan dalam domain pengguna yang diautentikasi

Error domainPolicy terjadi saat kebijakan untuk domain pengguna tidak mengizinkan akses ke Gmail oleh aplikasi Anda. Berikut adalah representasi JSON 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:

  1. Beri tahu pengguna bahwa domain tidak mengizinkan aplikasi Anda mengakses Gmail.
  2. Minta pengguna untuk menghubungi Admin domain guna meminta akses untuk aplikasi Anda.

Memecahkan error 429: Terlalu banyak permintaan

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 informasi tentang setiap batas. Namun, setiap batas dapat diselesaikan dengan mencoba mencoba ulang permintaan yang gagal atau dengan membagi pemrosesan di beberapa akun Gmail. Batas per pengguna tidak dapat ditingkatkan karena alasan apa pun. Untuk 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 gmail.com uji coba. Untuk batas ini, lihat Batas pengiriman Gmail di Google Workspace.

Batas ini berlaku per pengguna dan digunakan bersama oleh semua klien pengguna, baik klien API, klien native/web, maupun MSA SMTP. Jika batas ini terlampaui, error HTTP 429 Too Many Requests "Batas kapasitas pengguna terlampaui" "(Pengiriman email)" akan ditampilkan dengan waktu untuk mencoba lagi. Perhatikan bahwa batas harian yang terlampaui dapat menyebabkan jenis error ini selama beberapa jam sebelum permintaan diterima.

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

Batas bandwidth

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

Batasan ini biasanya hanya tercapai dalam situasi yang luar biasa atau penyalahgunaan. Jika batas ini terlampaui, error HTTP 429 Too Many Requests "Batas kapasitas pengguna terlampaui" akan ditampilkan dengan waktu untuk mencoba lagi. Perhatikan bahwa batas harian yang terlampaui dapat menyebabkan jenis error ini selama beberapa jam sebelum permintaan diterima.

Permintaan Serentak

Gmail API menerapkan batas permintaan serentak per pengguna (selain batas kapasitas per pengguna). Batas ini digunakan bersama oleh semua klien Gmail API yang mengakses pengguna tertentu 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 jumlah permintaan yang besar 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 "Terlalu banyak permintaan serentak untuk pengguna" akan ditampilkan.

Mengatasi error 500: Error backend

backendError terjadi saat error tidak terduga muncul saat memproses permintaan.

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

Untuk memperbaiki error ini, coba lagi permintaan yang gagal. Berikut adalah daftar error 500:

  • 502 Gateway Buruk
  • 503 Layanan Tidak Tersedia
  • 504 Waktu Tunggu Gateway

Mencoba lagi permintaan yang gagal untuk mengatasi error

Anda dapat mencoba lagi permintaan yang gagal secara berkala dengan menambah lamanya penundaan antara setiap permintaan yang gagal untuk menangani error yang terkait dengan batas kapasitas, volume jaringan, atau waktu respons. Misalnya, Anda dapat mencoba lagi permintaan yang gagal setelah satu detik, lalu setelah dua detik, lalu 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 minimal satu detik setelah error.

Melihat atau mengubah batas penggunaan, meningkatkan kuota

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

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

Permintaan batch

Penggunaan pengelompokan sangat dianjurkan, tetapi ukuran batch yang lebih besar cenderung memicu pembatasan kapasitas. Tidak disarankan untuk mengirim batch yang lebih besar dari 50 permintaan. Untuk mengetahui informasi tentang cara mengelompokkan permintaan, lihat Permintaan batch.