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 berisi petunjuk cara mengatasi error API tertentu.

Mengatasi error 400: Permintaan buruk

Error ini mungkin disebabkan oleh error berikut pada kode Anda:

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

Berikut adalah contoh representasi JSON untuk 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 tersebut:

{
  "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 Anda menggunakan library klien, library tersebut akan otomatis menangani pemuatan ulang 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.

Mengatasi error 403: Batas penggunaan terlampaui

Error 403 terjadi ketika 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 telah diautentikasi.

Untuk informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Mengatasi error 403: Batas harian terlampaui

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

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

Untuk memperbaiki error ini:

  1. Kunjungi Konsol API Google
  2. Pilih project Anda.
  3. Klik tab Quotas
  4. Minta kuota tambahan. Untuk mengetahui informasi lebih lanjut, lihat Meminta kuota tambahan.

Untuk informasi tambahan tentang batas Gmail, lihat Batas penggunaan.

Mengatasi error 403: Batas kapasitas pengguna terlampaui

Error userRateLimitExceeded menunjukkan bahwa batas per pengguna telah tercapai. Berikut adalah representasi JSON 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 optimalkan kode aplikasi Anda untuk membuat lebih sedikit permintaan atau permintaan percobaan ulang. Untuk mengetahui informasi tentang cara mencoba ulang permintaan, lihat Mencoba ulang 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 rasio permintaan maksimum Gmail API. Batas ini bervariasi bergantung pada jenis permintaan. Berikut adalah representasi JSON untuk error tersebut:

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

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

Error domainPolicy terjadi jika kebijakan untuk domain pengguna tidak mengizinkan akses ke Gmail oleh aplikasi Anda. Berikut adalah representasi JSON dari error tersebut:

{
  "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 menghubungi Admin domain untuk meminta akses untuk aplikasi Anda.

Mengatasi 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 lagi permintaan yang gagal atau dengan memisahkan 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 tersebut, 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, atau MSA SMTP. Jika batas ini melebihi, error "Batas tingkat pengguna terlampaui" "(Pengiriman email)" HTTP 429 Too Many Requests akan ditampilkan dengan waktu untuk mencoba lagi. Perlu diperhatikan bahwa batas harian yang terlampaui dapat menyebabkan jenis error ini selama beberapa jam sebelum permintaan diterima.

Pipeline pengiriman email bersifat kompleks: setelah pengguna melebihi kuota, mungkin akan ada penundaan selama beberapa menit sebelum API mulai menampilkan respons error 429. Jadi, Anda tidak dapat berasumsi bahwa respons 200 berarti email telah berhasil dikirim.

Batas bandwidth

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

Batasan ini biasanya hanya tercapai dalam situasi tertentu atau penyalahgunaan. Jika batas ini terlampaui, error "Batas tingkat pengguna terlampaui" Too Many Requests HTTP 429 akan ditampilkan dengan memberikan waktu untuk mencoba lagi. Perlu diperhatikan 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 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 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 "Terlalu banyak permintaan serentak untuk pengguna" pada HTTP 429 akan ditampilkan.Too Many Requests

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

Coba lagi permintaan yang gagal untuk mengatasi error

Anda dapat mencoba kembali permintaan yang gagal secara berkala dengan durasi yang lebih lama untuk menangani error yang terkait dengan batas kapasitas, volume jaringan, atau waktu respons. Misalnya, Anda mungkin 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 serta memaksimalkan throughput permintaan di lingkungan serentak.

Mulai periode percobaan ulang setidaknya satu detik setelah error.

Lihat atau ubah batas penggunaan, tingkatkan 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

Namun, penggunaan pengelompokan dianjurkan, tetapi ukuran tumpukan yang lebih besar kemungkinan akan memicu pembatasan kapasitas. Sebaiknya jangan mengirim batch yang lebih besar dari 50 permintaan. Untuk mengetahui informasi tentang cara mengelompokkan permintaan, lihat Membuat batch permintaan.