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 dan dapat menangani masalah dengan baik, mulai dari input yang tidak valid hingga ketidaktersediaan layanan 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 dari 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:

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

Memahami detail error

Selain kode tingkat atas, 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 individual GoogleAdsError.

Setiap GoogleAdsFailure objek berisi:

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

Setiap GoogleAdsError objek memberikan:

• errorCode: Kode error yang lebih mendetail, khusus untuk Google Ads API, seperti AuthenticationError.NOT_ADS_USER.
• message: Deskripsi error spesifik 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 (Kode 3) mungkin memiliki detail GoogleAdsFailure seperti ini:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.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 INVALID_ARGUMENT tingkat atas, 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 streaming panggilan, objek GoogleAdsFailure akan ditampilkan sebagai bagian dari metadata akhir 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 parsial

Jika Anda menggunakan kegagalan parsial, error untuk operasi yang gagal akan ditampilkan di kolom partial_failure_error respons, bukan di header respons. Dalam hal ini, the GoogleAdsFailure disematkan dalam a google.rpc.Status objek 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, panggilan tersebut akan berisi request_id.
• Metadata akhir: Untuk permintaan yang berhasil dan gagal, request-id tersedia dalam metadata akhir respons gRPC.
• Header respons: Untuk permintaan yang berhasil dan gagal, request-id juga tersedia di header respons gRPC dan respons HTTP, kecuali untuk permintaan streaming yang berhasil.
• SearchGoogleAdsStreamResponse: Untuk permintaan streaming, setiap SearchGoogleAdsStreamResponse pesan berisi kolom request_id.

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

Praktik terbaik untuk penanganan error

Untuk membangun aplikasi yang tangguh, terapkan praktik terbaik berikut:

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

2. Bedakan error klien dari error server:

   • Error klien: Kode seperti INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Kode ini memerlukan perubahan pada permintaan atau status/kredensial aplikasi Anda. Jangan coba lagi permintaan tanpa mengatasi masalah.
   • Error server: Kode seperti UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Kode ini menunjukkan masalah sementara dengan 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 meningkat di antara percobaan ulang. Hal ini membantu menghindari kelebihan beban pada layanan yang sudah tertekan. Misalnya, tunggu 1 detik, lalu 2 detik, lalu 4 detik, dan teruskan hingga jumlah maksimum percobaan ulang atau total waktu tunggu.
   • Jitter: Tambahkan sedikit "jitter" acak ke penundaan backoff untuk mencegah masalah "kawanan guntur" saat banyak klien mencoba lagi secara bersamaan.

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

5. Berikan masukan pengguna: Berdasarkan kode dan pesan GoogleAdsError tertentu, berikan masukan yang jelas dan bermanfaat kepada pengguna aplikasi Anda. Misalnya, bukan hanya "Terjadi error", Anda dapat mengatakan "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.