Menangani error API

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

Bagian selanjutnya dari halaman ini memberikan referensi error Kalender, beserta beberapa panduan tentang cara menanganinya di aplikasi Anda.

Sebaiknya uji penanganan error aplikasi Anda di lingkungan yang sebenarnya.

Menerapkan backoff eksponensial

Dokumentasi Cloud API menjelaskan dengan baik tentang penundaan eksponensial dan cara menggunakannya dengan Google API.

Error & tindakan yang disarankan

Bagian ini memberikan representasi JSON lengkap dari setiap kesalahan yang tercantum dan tindakan yang disarankan yang dapat Anda lakukan untuk menanganinya.

400: Bad Request

Kesalahan pengguna. Hal ini dapat berarti bahwa kolom atau parameter wajib diisi belum disediakan, nilai yang diberikan tidak valid, atau kombinasi kolom yang diberikan tidak valid.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "timeRangeEmpty",
    "message": "The specified time range is empty.",
    "locationType": "parameter",
    "location": "timeMax",
   }
  ],
  "code": 400,
  "message": "The specified time range is empty."
 }
}

Tindakan yang disarankan: Karena ini adalah error permanen, jangan coba lagi. Baca pesan error dan ubah permintaan Anda sesuai dengan pesan error tersebut.

401: Kredensial Tidak Valid

Header otorisasi tidak valid. Token akses yang Anda gunakan sudah tidak berlaku atau tidak valid.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "authError",
    "message": "Invalid Credentials",
    "locationType": "header",
    "location": "Authorization",
   }
  ],
  "code": 401,
  "message": "Invalid Credentials"
 }
}

Saran tindakan:

• Dapatkan token akses baru menggunakan token refresh yang berlaku lama.
• Jika hal ini gagal, arahkan pengguna melalui alur OAuth, seperti yang dijelaskan dalam Mengizinkan permintaan dengan OAuth 2.0.
• Jika Anda melihat pesan ini untuk akun layanan, periksa untuk memastikan bahwa Anda telah berhasil menyelesaikan semua langkah di halaman akun layanan.

403: User Rate Limit Exceeded

Salah satu batas dari Konsol Developer telah tercapai.

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

Saran tindakan:

• Pastikan aplikasi Anda mengikuti praktik terbaik dari mengelola kuota.
• Tingkatkan kuota per pengguna di project Konsol Developer.
• Jika satu pengguna membuat banyak permintaan atas nama banyak pengguna akun Google Workspace, pertimbangkan untuk menggunakan akun layanan dengan delegasi tingkat domain dan menyetel parameter quotaUser.
• Gunakan backoff eksponensial.

403: Rate Limit Exceeded

Pengguna telah mencapai kecepatan permintaan maksimum Google Calendar API per kalender atau per pengguna yang diautentikasi.

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

Tindakan yang disarankan: Error rateLimitExceeded dapat menampilkan kode error 403 atau 429—saat ini keduanya memiliki fungsi yang sama dan harus direspons dengan cara yang sama, yaitu menggunakan backoff eksponensial. Selain itu, pastikan aplikasi Anda mengikuti praktik terbaik dari mengelola kuota.

403: Batas penggunaan Kalender terlampaui

Pengguna mencapai salah satu batas Google Kalender yang diterapkan untuk melindungi pengguna dan infrastruktur Google dari penyalahgunaan.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

Saran tindakan:

• Baca selengkapnya tentang batas penggunaan Kalender di bantuan Administrator Google Workspace.

403: Dilarang untuk non-penyelenggara

Permintaan pembaruan acara berupaya menyetel salah satu properti acara bersama dalam salinan yang bukan milik penyelenggara. Properti bersama (misalnya, guestsCanInviteOthers, guestsCanModify, atau guestsCanSeeOtherGuests) hanya dapat ditetapkan oleh penyelenggara.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "forbiddenForNonOrganizer",
    "message": "Shared properties can only be changed by the organizer of the event."
   }
  ],
  "code": 403,
  "message": "Shared properties can only be changed by the organizer of the event."
 }
}

Saran tindakan:

• Jika Anda menggunakan Events: insert, Events: import, atau Events: update, dan permintaan Anda tidak menyertakan properti bersama, hal ini sama dengan mencoba menyetelnya ke nilai default. Sebaiknya gunakan Events: patch.
• Jika permintaan Anda memiliki properti bersama, pastikan Anda hanya mencoba mengubah properti ini jika Anda memperbarui salinan penyelenggara.

404: Tidak Ditemukan

Resource yang ditentukan tidak ditemukan. Hal ini dapat terjadi dalam beberapa kasus. Berikut beberapa contohnya:

• jika resource yang diminta (dengan ID yang diberikan) tidak pernah ada

• saat mengakses kalender yang tidak dapat diakses pengguna

  { "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "Not Found" } ], "code": 404, "message": "Not Found" } }

Tindakan yang disarankan: Gunakan backoff eksponensial.

409: ID yang diminta sudah ada

Instance dengan ID yang diberikan sudah ada di penyimpanan.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "duplicate",
    "message": "The requested identifier already exists."
   }
  ],
  "code": 409,
  "message": "The requested identifier already exists."
 }
}

Tindakan yang disarankan: Buat ID baru jika Anda ingin membuat instance baru, atau gunakan panggilan metode update.

409: Conflict

Item yang dikelompokkan dalam operasi events.batch tidak dapat dieksekusi karena konflik operasional dengan item yang dikelompokkan lain yang diminta.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conflict",
    "message": "Conflict"
   }
  ],
  "code": 409,
  "message": "Conflict"
 }
}

Tindakan yang disarankan: Kecualikan semua item batch yang berhasil diselesaikan dan semua item batch yang pasti gagal, lalu coba lagi item yang tersisa dalam operasi batch events.batch atau operasi peristiwa tunggal yang sesuai.

410: Gone

Parameter syncToken atau updatedMin tidak lagi valid. Error ini juga dapat terjadi jika permintaan mencoba menghapus acara yang sudah dihapus.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "fullSyncRequired",
    "message": "Sync token is no longer valid, a full sync is required.",
    "locationType": "parameter",
    "location": "syncToken",
    }
  ],
  "code": 410,
  "message": "Sync token is no longer valid, a full sync is required."
 }
}

atau

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "updatedMinTooLongAgo",
    "message": "The requested minimum modification time lies too far in the past.",
    "locationType": "parameter",
    "location": "updatedMin",
   }
  ],
  "code": 410,
  "message": "The requested minimum modification time lies too far in the past."
 }
}

atau

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "deleted",
    "message": "Resource has been deleted"
   }
  ],
  "code": 410,
  "message": "Resource has been deleted"
 }
}

Tindakan yang disarankan: Untuk parameter syncToken atau updatedMin, hapus penyimpanan dan sinkronkan ulang. Untuk mengetahui detail selengkapnya, lihat Menyinkronkan Resource Secara Efisien. Untuk acara yang sudah dihapus, Anda tidak perlu melakukan tindakan lebih lanjut.

412: Precondition Failed

ETag yang diberikan di header If-match tidak lagi sesuai dengan ETag resource saat ini.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conditionNotMet",
    "message": "Precondition Failed",
    "locationType": "header",
    "location": "If-Match",
    }
  ],
  "code": 412,
  "message": "Precondition Failed"
 }
}

Tindakan yang disarankan: Ambil ulang entitas dan terapkan kembali perubahan. Untuk mengetahui detail selengkapnya, lihat Mendapatkan versi resource tertentu.

429: Terlalu banyak permintaan

Error rateLimitExceeded terjadi saat pengguna telah mengirim terlalu banyak permintaan dalam jangka waktu tertentu.

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

Tindakan yang disarankan: Error rateLimitExceeded dapat menampilkan kode error 403 atau 429—saat ini keduanya memiliki fungsi yang sama dan harus direspons dengan cara yang sama, yaitu menggunakan backoff eksponensial. Selain itu, pastikan aplikasi Anda mengikuti praktik terbaik dari mengelola kuota.

500: Error Backend

Terjadi error yang tidak terduga saat memproses permintaan.

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

Tindakan yang disarankan: Gunakan backoff eksponensial.