Menangani error API

Google 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 lain di halaman ini menyediakan referensi error Kalender, dengan beberapa panduan tentang cara menanganinya di aplikasi Anda.

Uji penanganan error aplikasi Anda di lingkungan sebenarnya. Untuk mengetahui informasi selengkapnya, lihat Menangani batas kuota pengujian.

Menerapkan backoff eksponensial

Dokumentasi Google Cloud Storage menjelaskan backoff eksponensial dan cara menggunakannya dengan Google API.

Error dan tindakan yang disarankan

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

400: Bad Request

Kesalahan pengguna. Error ini terjadi jika Anda tidak memberikan kolom atau parameter yang diperlukan, memberikan nilai yang tidak valid, atau memberikan kombinasi kolom yang 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: Invalid Credentials

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"
  }
}

Tindakan yang disarankan:

• Dapatkan token akses baru menggunakan token refresh yang berlaku lama.
• Jika gagal, arahkan pengguna melalui alur OAuth, seperti yang dijelaskan dalam Mengotorisasi permintaan dengan OAuth 2.0.
• Jika error ini terjadi untuk akun layanan, pastikan Anda telah berhasil menyelesaikan semua langkah di halaman akun layanan.

403: User Rate Limit Exceeded

Salah satu batas dari Konsol Google Cloud telah tercapai.

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

Tindakan yang disarankan:

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

403: Rate Limit Exceeded

Pengguna telah mencapai rasio permintaan maksimum 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: rateLimitExceeded error dapat menampilkan kode error 403 atau 429 —secara fungsional serupa dan Anda harus menanganinya dengan cara yang sama, menggunakan backoff eksponensial. Selain itu, pastikan aplikasi Anda mengikuti praktik terbaik dari mengelola kuota.

403: Calendar usage limits exceeded

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

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

Tindakan yang disarankan:

• Baca lebih lanjut tentang batas penggunaan Kalender di Bantuan Admin Google Workspace.

403: Forbidden for non-organizer

Permintaan pembaruan acara mencoba menetapkan salah satu properti acara bersama dalam salinan yang bukan milik penyelenggara. Hanya penyelenggara yang dapat menetapkan properti bersama (misalnya, guestsCanInviteOthers, guestsCanModify, atau guestsCanSeeOtherGuests).

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

Tindakan yang disarankan:

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

404: Not Found

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

• Saat 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: The requested identifier already exists

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; jika tidak, gunakan metode events.update.

409: Conflict

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

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

Tindakan yang disarankan: Hapus item yang selesai dan gagal, lalu coba lagi item yang tersisa dalam events.batch yang berbeda atau operasi acara tunggal yang sesuai.

410: Gone

Parameter syncToken atau updatedMin tidak lagi valid. Error ini juga dapat terjadi jika permintaan mencoba menghapus acara yang telah 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 lakukan sinkronisasi ulang. Untuk mengetahui detail selengkapnya, lihat Menyinkronkan resource secara efisien. Untuk acara yang sudah dihapus, tidak ada tindakan lebih lanjut yang diperlukan.

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 entity dan terapkan kembali perubahan. Untuk mengetahui detail selengkapnya, lihat Mendapatkan versi resource tertentu.

429: Too many requests

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

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

Tindakan yang disarankan: rateLimitExceeded error dapat menampilkan kode error 403 atau 429 —secara fungsional serupa dan Anda harus menanganinya dengan cara yang sama, menggunakan backoff eksponensial. Selain itu, pastikan aplikasi Anda mengikuti praktik terbaik dari mengelola kuota.

500: Backend Error

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.