Saat Anda mengirim permintaan ke Google Ads API, permintaan tersebut mungkin gagal karena berbagai alasan. Misalnya, Anda mungkin memberikan argumen yang tidak valid, atau akun Anda mungkin telah mencapai batas untuk membuat kampanye baru. Dalam kasus tersebut, API akan menampilkan error untuk memberi tahu Anda apa yang salah.
Panduan ini menjelaskan cara membaca dan menangani error API agar Anda dapat membangun aplikasi yang lebih tangguh.
Struktur error
Jika Anda menggunakan salah satu library klien kami, error API akan ditampilkan sebagai pengecualian. Pengecualian ini berisi detail yang membantu Anda memahami penyebab terjadinya error.
Google Ads API menampilkan informasi error dalam format standar. Jika terjadi
error, respons akan berisi objek
GoogleAdsFailure. Objek ini berisi daftar objek GoogleAdsError individual, yang masing-masing menjelaskan error tertentu.
Setiap objek GoogleAdsError menyediakan:
error_code: Kode error tertentu yang memberi tahu Anda jenis error, sepertiAuthenticationError.NOT_ADS_USER.message: Deskripsi yang dapat dibaca manusia tentang alasan terjadinya error.trigger: Nilai yang menyebabkan error, seperti "1234".location: Detail tentang bagian permintaan yang menyebabkan error, seperti nama kolom tertentu.
Selain daftar error, GoogleAdsFailure berisi requestId, yang merupakan ID unik untuk permintaan API yang menyebabkan error.
Contoh error
Berikut adalah contoh tampilan error dalam format JSON. Error ini
menunjukkan bahwa kolom name dari ad_group pada indeks 0 tidak ada dalam
permintaan.
{
"code": 3,
"message": "Request contains an invalid argument.",
"details": [
{
"@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
"errors": [
{
"errorCode": {
"requestError": "REQUIRED_FIELD_MISSING"
},
"message": "Required field is missing",
"location": {
"fieldPathElements": [
{
"fieldName": "ad_group",
"index": 0
},
{
"fieldName": "name"
}
]
}
}
],
"requestId": "unique_request_id_12345"
}
]
}
Lihat Memahami error API untuk mempelajari error API lebih lanjut.
Contoh library klien
Bagian berikut menunjukkan cara menangani error di berbagai library klien.
Java
try {
// Make an API call.
...
} catch (GoogleAdsException gae) {
// GoogleAdsException is the base class for most exceptions thrown by an
// API request. Instances of this exception have a message and a
// GoogleAdsFailure that contains a collection of GoogleAdsErrors that
// indicate the underlying causes of the GoogleAdsException.
System.err.printf(
"Request ID %s failed due to GoogleAdsException. Underlying"
+ " errors:%n",
gae.getRequestId());
int i = 0;
for (GoogleAdsError googleAdsError :
gae.getGoogleAdsFailure().getErrorsList()) {
System.err.printf(" Error %d: %s%n", i++, googleAdsError);
}
}
C#
try
{
// Make an API call.
...
}
catch (GoogleAdsException e)
{
Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
Console.WriteLine("Google Ads failure details:");
foreach (GoogleAdsError error in e.Failure.Errors)
{
Console.WriteLine($"{error.ErrorCode}: {error.Message}");
}
}
PHP
try {
// Make an API call.
...
} catch (GoogleAdsException $googleAdsException) {
printf(
"Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
$googleAdsException->getRequestId(),
PHP_EOL,
PHP_EOL
);
$errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
foreach ($errors as $error) {
/** @var GoogleAdsError $error */
printf(
"\t%s: %s%s",
$error->getErrorCode()->getErrorCode(),
$error->getMessage(),
PHP_EOL
);
}
}
Python
try:
# Make an API call.
...
except GoogleAdsException as ex:
print(
f"Request with ID '{ex.request_id}' failed with status "
f"'{ex.error.code().name}' and includes the following errors:"
)
for error in ex.failure.errors:
print(
f"\tError with message '{error.message}' and code "
f"'{error.error_code}'."
)
Ruby
begin
# Make an API call.
...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
puts "API call failed with request ID: #{e.request_id}"
e.failure.errors.each do |error|
puts "\t#{error.error_code}: #{error.message}"
end
end
Perl
# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
printf "Google Ads failure details:\n";
foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
printf "\t%s: %s\n",
[keys %{$error->{errorCode}}]->[0], $error->{message};
}
}
Cara merekam log
Untuk memecahkan masalah error, ambil log error yang ditampilkan oleh server Google Ads API dan periksa kontennya. Gunakan petunjuk berikut untuk mengaktifkan logging dan merekam log API.
Java
Lihat panduan logging library klien Java untuk mengetahui petunjuknya.
C#
Anda dapat melakukan inisialisasi logging dengan menambahkan baris berikut dalam metode Main
sebelum melakukan panggilan API. Tindakan ini memastikan bahwa library membuat log untuk semua panggilan API yang dilakukan oleh aplikasi Anda.
using Google.Ads.GoogleAds.Util;
...
// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
"/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);
// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
"/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);
Lihat panduan logging library.NET untuk mengetahui opsi tambahan.
PHP
Anda dapat menyetel konfigurasi logging di file
google_ads_php.ini
library klien. Tetapkan logLevel ke NOTICE untuk mulai mencatat log error
mendetail.
[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"
Lihat panduan logging library klien PHP untuk mendapatkan petunjuk.
Python
Anda dapat menetapkan konfigurasi logging di file google-ads.yaml library klien. Tetapkan level logging ke DEBUG untuk mulai merekam log error mendetail.
Lihat panduan logging library Python untuk opsi tambahan.
Ruby
Anda dapat menyetel konfigurasi logging di file
google_ads_config.rb
library klien. Tetapkan level logging ke INFO untuk mulai merekam log error mendetail.
Lihat panduan logging library Ruby untuk mengetahui opsi tambahan.
Perl
Untuk menginisialisasi logging, tambahkan baris berikut dalam skrip Perl Anda sebelum melakukan panggilan API.
Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();
Lihat panduan logging library Perl untuk mengetahui opsi tambahan.
curl
curl mencetak respons yang gagal ke stderr secara default.
Cara menangani error
Jika Anda mengalami error, berikut langkah-langkah yang harus dilakukan:
- Tangkap pengecualian dan ambil log: Mulai dengan menangkap pengecualian dan secara opsional mengambil log API.
- Periksa daftar
errors: Lihat setiapGoogleAdsErrordi objekGoogleAdsFailure.error_codedanmessageakan memberi tahu Anda apa yang salah. - Periksa nilai
location: Kolomlocationdapat membantu Anda mengidentifikasi bagian permintaan yang mengalami masalah. - Lihat dokumentasi: Untuk kode error tertentu, periksa halaman error umum atau referensi kode error lengkap untuk mengetahui detail selengkapnya tentang error dan cara memperbaikinya.
- Sesuaikan permintaan Anda: Berdasarkan pesan error, perbaiki permintaan API Anda. Misalnya, jika Anda melihat
REQUIRED_FIELD_MISSING, pastikan Anda menyediakan kolom tersebut dalam permintaan Anda. - Catat
request_id: Jika Anda tidak dapat mengetahui cara menyelesaikan error dan perlu menghubungi dukungan, sertakan log permintaan dan respons lengkap untuk permintaan yang gagal. Pastikan untuk menyertakanrequest_id. ID ini membantu engineer Google menemukan detail permintaan yang gagal di log server Google Ads API dan menyelidiki masalah Anda.
Langkah berikutnya
- Tinjau Error umum untuk mengetahui daftar masalah umum dan solusinya.
- Untuk teknik penanganan error yang lebih lanjut, termasuk logika percobaan ulang dan kegagalan parsial, lihat Memahami error API.