Kami telah mengelompokkan error ke dalam kategori umum berikut:
- Autentikasi
- Error yang dapat dicoba ulang
- Validasi
- Terkait sinkronisasi
Meskipun kategori ini tidak mencakup semua kemungkinan error, dan beberapa mungkin cocok dengan lebih dari satu kategori, kategori tersebut dapat menjadi titik awal untuk menyusun penanganan error aplikasi Anda. Lihat referensi berikut untuk mengetahui detail selengkapnya tentang error tertentu:
- Error umum memberikan detail selengkapnya tentang error tertentu.
google.rpc.Statusmemberikan detail tentang model error logis yang digunakan oleh API.- Kode error kanonis memberikan daftar dan penjelasan kode error kanonis yang ditentukan oleh gRPC dan HTTP dalam konteks Google Ads API.
Error autentikasi
Autentikasi mengacu pada apakah aplikasi Anda telah diberi izin oleh pengguna untuk mengakses Google Ads atas nama mereka. Autentikasi dikelola melalui kredensial yang dihasilkan oleh alur OAuth2.
Alasan paling umum munculnya error autentikasi dari faktor di luar
kendali Anda adalah pengguna yang diautentikasi telah mencabut izin yang mereka berikan kepada aplikasi
Anda untuk bertindak atas nama mereka. Misalnya, jika aplikasi Anda mengelola akun Google Ads terpisah untuk klien independen dan melakukan autentikasi secara terpisah sebagai setiap klien saat mengelola akun klien tersebut, klien dapat mencabut akses aplikasi Anda kapan saja. Bergantung pada kapan akses Anda dicabut, API dapat langsung menampilkan
error AuthenticationError.OAUTH_TOKEN_REVOKED, atau
objek kredensial bawaan di library klien dapat menampilkan
pengecualian token dicabut. Dalam kedua kasus tersebut, jika aplikasi Anda memiliki UI untuk klien, aplikasi dapat meminta mereka meluncurkan kembali alur OAuth2 untuk menetapkan kembali izin aplikasi Anda untuk bertindak atas nama mereka.
Terkait hal ini, jika project Google Cloud Anda hanya memiliki Tingkat akses
pengujian dan mencoba membuat permintaan terhadap akun produksi
(non-pengujian), API akan menampilkan
AuthorizationError yang nilai enum-nya bergantung pada versi
API:
- Mulai
v25: PengembalianAuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION. v24dan yang lebih lama: MenampilkanAuthorizationError.ACTION_NOT_PERMITTED.
Error yang dapat dicoba ulang
Beberapa error, seperti TRANSIENT_ERROR atau
INTERNAL_ERROR, dapat mengindikasikan masalah sementara yang mungkin dapat
diselesaikan dengan mencoba kembali permintaan setelah jeda singkat.
Untuk permintaan yang dimulai oleh pengguna, salah satu strateginya adalah segera menunjukkan error di UI Anda dan memberi pengguna opsi untuk memicu percobaan ulang. Atau, aplikasi Anda dapat otomatis mencoba ulang permintaan terlebih dahulu, dan hanya menampilkan error di UI setelah mencapai jumlah percobaan ulang maksimum atau total waktu tunggu pengguna.
Untuk permintaan yang dimulai di backend, aplikasi Anda harus otomatis mencoba ulang permintaan hingga jumlah percobaan ulang maksimum.
Saat Anda mencoba kembali permintaan, gunakan kebijakan backoff eksponensial dengan jitter acak. Misalnya, jika Anda pertama kali menjeda 5 detik sebelum percobaan ulang pertama, Anda dapat menjeda 10 detik setelah percobaan ulang kedua dan 20 detik setelah percobaan ulang ketiga, dengan menambahkan penundaan acak kecil ke setiap interval untuk mencegah lonjakan percobaan ulang yang disinkronkan. Backoff eksponensial membantu memastikan Anda tidak memanggil API terlalu agresif. Jika error berlanjut setelah mencoba ulang, catat
request-id dari respons untuk pemecahan masalah.
Error validasi
Error validasi menunjukkan bahwa input ke operasi tidak dapat diterima.
Contohnya meliputi PolicyViolationError,
DateError, DateRangeError,
StringLengthError, dan
UrlFieldError.
Error validasi paling sering terjadi dalam permintaan yang dimulai pengguna, saat pengguna memasukkan input yang tidak valid. Dalam kasus ini, Anda harus memberikan pesan error yang sesuai kepada pengguna berdasarkan error API tertentu yang Anda terima. Anda juga dapat memvalidasi input pengguna untuk kesalahan umum sebelum melakukan panggilan API, sehingga membuat aplikasi Anda lebih responsif dan penggunaan API Anda lebih efisien. Untuk permintaan dari backend, aplikasi Anda dapat menambahkan operasi yang gagal ke antrean untuk ditinjau oleh operator manusia.
Error terkait sinkronisasi
Banyak aplikasi Google Ads mengelola database lokal untuk menyimpan objek Google Ads. Salah satu tantangan dari pendekatan ini adalah database lokal mungkin tidak sinkron dengan objek sebenarnya di Google Ads. Misalnya, pengguna mungkin menghapus grup iklan langsung di Google Ads, tetapi aplikasi dan database lokal tidak mengetahui perubahan tersebut dan terus mengeluarkan panggilan API seolah-olah grup iklan tersebut ada. Masalah sinkronisasi ini dapat muncul sebagai berbagai error seperti DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD, dan banyak lainnya.
Untuk permintaan yang dimulai oleh pengguna, salah satu strateginya adalah memberi tahu pengguna tentang kemungkinan masalah sinkronisasi, segera meluncurkan tugas yang mengambil class objek Google Ads yang relevan dan memperbarui database lokal, lalu meminta pengguna untuk memuat ulang UI.
Untuk permintaan backend, beberapa error memberikan informasi yang cukup bagi aplikasi Anda untuk
memperbaiki database lokal secara otomatis dan bertahap. Misalnya,
CANNOT_OPERATE_ON_REMOVED_ADGROUPAD
akan menyebabkan aplikasi Anda menandai iklan tersebut sebagai dihapus di database lokal Anda. Error
yang tidak dapat Anda tangani dengan cara ini dapat menyebabkan aplikasi meluncurkan tugas
sinkronisasi yang lebih lengkap atau ditambahkan ke antrean untuk ditinjau oleh operator manusia.