Memahami error API

Panduan ini menjelaskan cara Google Ads API menangani dan mengomunikasikan error. Memahami struktur dan arti error API sangat penting untuk membangun aplikasi yang tangguh yang dapat menangani masalah dengan baik, mulai dari input yang tidak valid hingga layanan yang tidak tersedia untuk sementara.

Google Ads API mengikuti model error Google API standar, yang didasarkan pada kode Status gRPC. Setiap respons API yang menghasilkan error menyertakan objek Status yang berisi:

  • Kode error numerik.
  • Pesan error.
  • Opsional, detail error tambahan.

Kode error kanonis

Google Ads API menggunakan serangkaian kode error kanonis yang ditentukan oleh gRPC dan HTTP. Kode ini memberikan indikasi tingkat tinggi tentang jenis error. Anda harus selalu memeriksa kode numerik ini terlebih dahulu untuk memahami sifat mendasar dari masalah tersebut.

Tabel berikut merangkum kode paling umum yang mungkin Anda temui saat menggunakan Google Ads API:

Kode gRPC Kode HTTP Nama enum Deskripsi Panduan
0 200 OK Tidak ada error; menunjukkan keberhasilan. T/A
1 499 CANCELLED Operasi dibatalkan, biasanya oleh klien. Biasanya berarti klien berhenti menunggu. Periksa waktu tunggu sisi klien.
2 500 UNKNOWN Terjadi error tak dikenal. Detail selengkapnya mungkin ada di pesan atau detail error. Diperlakukan sebagai error server. Sering kali dapat dicoba lagi dengan backoff.
3 400 INVALID_ARGUMENT Klien menetapkan argumen yang tidak valid. Hal ini menunjukkan masalah yang mencegah API memproses permintaan, seperti nama resource yang salah format atau nilai yang tidak valid. Error klien: Tinjau parameter permintaan Anda dan pastikan parameter tersebut memenuhi persyaratan API. Detail error biasanya memberikan informasi tentang argumen mana yang tidak valid dan bagaimana—gunakan detail ini untuk memperbaiki permintaan. Jangan mencoba lagi tanpa memperbaiki permintaan.
4 504 DEADLINE_EXCEEDED Batas waktu berakhir sebelum operasi selesai. Error server: Sering kali bersifat sementara. Pertimbangkan untuk mencoba lagi dengan backoff eksponensial.
5 404 NOT_FOUND Beberapa entitas yang diminta, seperti kampanye atau grup iklan, tidak ditemukan. Error klien: Verifikasi keberadaan dan ID resource yang Anda coba akses. Jangan coba lagi tanpa koreksi.
6 409 ALREADY_EXISTS Entitas yang coba dibuat oleh klien sudah ada. Error klien: Hindari pembuatan resource duplikat. Periksa apakah resource ada sebelum mencoba membuatnya.
7 403 PERMISSION_DENIED Pemanggil tidak memiliki izin untuk menjalankan operasi yang ditentukan. Error klien: Periksa autentikasi, otorisasi, dan peran pengguna untuk akun Google Ads. Jangan coba lagi tanpa menyelesaikan izin.
8 429 RESOURCE_EXHAUSTED Resource telah habis (misalnya, Anda telah melampaui kuota), atau sistem mengalami kelebihan beban. Error Klien/Server: Biasanya memerlukan waktu tunggu. Terapkan backoff eksponensial dan berpotensi mengurangi frekuensi permintaan. Lihat Batas dan kuota API.
9 400 FAILED_PRECONDITION Operasi tersebut ditolak karena sistem tidak dalam keadaan dibutuhkan untuk menjalankan operasi. Misalnya, kolom wajib diisi tidak ada. Error klien: Permintaan valid, tetapi status salah. Tinjau detail error untuk memahami kegagalan prasyarat. Jangan coba lagi tanpa mengoreksi negara bagian.
10 409 ABORTED Operasi dibatalkan, biasanya karena masalah konkurensi seperti konflik transaksi. Error server: Sering kali aman untuk dicoba lagi dengan backoff singkat.
11 400 OUT_OF_RANGE Upaya operasi dilakukan melampaui rentang yang valid. Error klien: Perbaiki rentang atau indeks.
12 501 UNIMPLEMENTED Operasi tidak diterapkan atau tidak didukung oleh API. Error klien: Periksa versi API dan fitur yang tersedia. Jangan coba lagi.
13 500 INTERNAL Terjadi error internal. Ini adalah penampung umum untuk masalah sisi server. Error server: Umumnya dapat dicoba lagi dengan backoff eksponensial. Jika berlanjut, laporkan masalah tersebut.
14 503 UNAVAILABLE Saat ini layanan tidak tersedia. Kemungkinan besar ini hanya kondisi sementara. Error server: Sangat direkomendasikan untuk mencoba lagi dengan backoff eksponensial.
15 500 DATA_LOSS Data hilang atau rusak yang tidak dapat dipulihkan. Error server: Jarang terjadi. Menunjukkan masalah serius. Jangan coba lagi. Jika berlanjut, laporkan masalah tersebut.
16 401 UNAUTHENTICATED Permintaan tidak memiliki kredensial autentikasi yang valid. Error klien: Verifikasi token autentikasi dan kredensial Anda. Jangan coba lagi tanpa memperbaiki autentikasi.

Untuk mengetahui detail selengkapnya tentang kode ini, lihat Panduan Desain API - Kode error.

Memahami detail error

Selain kode tingkat teratas, Google Ads API memberikan informasi error yang lebih spesifik dalam kolom details objek Status. Kolom ini sering kali berisi proto GoogleAdsFailure, yang mencakup daftar objek GoogleAdsError individual.

Setiap objek GoogleAdsFailure berisi:

  • errors: Daftar objek GoogleAdsError, yang masing-masing menjelaskan error tertentu yang terjadi.
  • request_id: ID unik untuk permintaan, berguna untuk tujuan proses debug dan dukungan.

Setiap objek GoogleAdsError menyediakan:

  • errorCode: Kode error khusus Google Ads API yang lebih terperinci, seperti AuthenticationError.NOT_ADS_USER.
  • message: Deskripsi error tertentu yang dapat dibaca manusia.
  • trigger: Nilai yang menyebabkan error, jika berlaku.
  • location: Menjelaskan lokasi terjadinya error dalam permintaan, termasuk jalur kolom.
  • details: Detail error tambahan, seperti alasan error yang tidak dipublikasikan.

Contoh detail error

Saat Anda menerima error, library klien akan memungkinkan Anda mengakses detail ini. Misalnya, INVALID_ARGUMENT (Code 3) dapat memiliki detail GoogleAdsFailure seperti ini:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

Dalam contoh ini, meskipun ada INVALID_ARGUMENT tingkat teratas, detail GoogleAdsFailure memberi tahu Anda bahwa kolom name dan description menyebabkan masalah dan alasannya (REQUIRED dan TOO_SHORT, masing-masing).

Menemukan detail error

Cara Anda mengakses detail error bergantung pada apakah Anda menggunakan panggilan API standar, kegagalan parsial, atau streaming.

Panggilan API standar dan streaming

Jika panggilan API gagal tanpa menggunakan kegagalan parsial, termasuk panggilan streaming, objek GoogleAdsFailure akan ditampilkan sebagai bagian dari metadata berikutnya di header respons gRPC. Jika Anda menggunakan REST untuk panggilan standar, GoogleAdsFailure akan ditampilkan dalam respons HTTP. Library klien biasanya menampilkan hal ini sebagai pengecualian dengan atribut GoogleAdsFailure.

Kegagalan sebagian

Jika Anda menggunakan kegagalan sebagian, error untuk operasi yang gagal ditampilkan di kolom partial_failure_error respons, bukan di header respons. Dalam hal ini, GoogleAdsFailure disematkan dalam objek google.rpc.Status dalam respons.

Tugas batch

Untuk pemrosesan batch, error untuk operasi individual dapat ditemukan dengan mengambil hasil tugas batch setelah tugas selesai. Setiap hasil operasi akan menyertakan kolom status yang berisi detail error jika operasi gagal.

ID Permintaan

request-id adalah string unik yang mengidentifikasi permintaan API Anda dan penting untuk pemecahan masalah.

Anda dapat menemukan request-id di beberapa tempat:

  • GoogleAdsFailure: Jika panggilan API gagal dan GoogleAdsFailure ditampilkan, maka akan berisi request_id.
  • Metadata akhir: Untuk permintaan yang berhasil dan gagal, request-id tersedia di metadata akhir respons gRPC.
  • Header respons: Untuk permintaan yang berhasil dan gagal, request-id juga tersedia di header respons gRPC dan HTTP, kecuali untuk permintaan streaming yang berhasil.
  • SearchGoogleAdsStreamResponse: Untuk permintaan streaming, setiap pesan SearchGoogleAdsStreamResponse berisi kolom request_id.

Saat mencatat error atau menghubungi dukungan, pastikan untuk menyertakan request-id untuk membantu mendiagnosis masalah.

Praktik terbaik untuk penanganan error

Untuk membangun aplikasi yang tangguh, terapkan praktik terbaik berikut:

  1. Periksa detail error: Selalu parsing kolom details dari objek Status, khususnya cari GoogleAdsFailure. errorCode, message, dan location terperinci dalam GoogleAdsError memberikan informasi yang paling dapat ditindaklanjuti untuk proses debug dan masukan pengguna.

  2. Membedakan error klien dari error server:

    • Error klien: Kode seperti INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Error ini memerlukan perubahan pada permintaan atau status/kredensial aplikasi Anda. Jangan coba lagi permintaan tanpa mengatasi masalahnya.
    • Error server: Kode seperti UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Hal ini menunjukkan adanya masalah sementara pada layanan API.

  3. Terapkan strategi percobaan ulang:

    • Kapan harus mencoba lagi: Coba lagi hanya untuk error server sementara seperti UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, dan ABORTED.
    • Backoff eksponensial: Gunakan algoritma backoff eksponensial untuk menunggu periode yang semakin meningkat di antara percobaan ulang. Hal ini membantu menghindari membebani layanan yang sudah tertekan. Misalnya, tunggu 1 detik, lalu 2 detik, lalu 4 detik, dan seterusnya hingga jumlah maksimum percobaan ulang atau total waktu tunggu.
    • Jitter: Tambahkan sejumlah kecil "jitter" acak ke penundaan mundur untuk mencegah masalah "kawanan guntur" saat banyak klien mencoba ulang secara bersamaan.

  4. Catat secara menyeluruh: Catat respons error lengkap, termasuk semua detail, terutama ID permintaan. Informasi ini sangat penting untuk proses penelusuran bug dan untuk melaporkan masalah ke dukungan Google jika diperlukan.

  5. Memberikan masukan pengguna: Berdasarkan kode dan pesan GoogleAdsError tertentu, berikan masukan yang jelas dan bermanfaat kepada pengguna aplikasi Anda. Misalnya, alih-alih hanya menampilkan "Terjadi error", Anda dapat menampilkan "Nama kampanye wajib diisi" atau "ID grup iklan yang diberikan tidak ditemukan".

Dengan mengikuti panduan ini, Anda dapat mendiagnosis dan menangani error yang ditampilkan oleh Google Ads API secara efektif, sehingga menghasilkan aplikasi yang lebih stabil dan mudah digunakan.