Menangani error API

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 seperti itu, API akan menampilkan error untuk memberi tahu Anda apa yang salah.

Panduan ini menjelaskan cara membaca dan menangani error API sehingga Anda dapat membuat aplikasi yang lebih andal.

Struktur error

Jika Anda menggunakan salah satu library klien kami, error API akan ditampilkan sebagai pengecualian. Pengecualian ini berisi detail yang membantu Anda memahami alasan 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 memberikan:

  • error_code: Kode error tertentu yang memberi tahu Anda jenis error, seperti AuthenticationError.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 menghasilkan 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.v24.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 panduan kami untuk mempelajari lebih lanjut error API.

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
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() 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 '{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 mengambil 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 mengambil log API.

Java

Lihat panduan logging library klien Java untuk mengetahui petunjuknya.

C#

Anda dapat menginisialisasi logging dengan menambahkan baris berikut dalam metode Main sebelum melakukan panggilan API. Tindakan ini memastikan bahwa semua 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 menetapkan konfigurasi logging di file google_ads_php.ini library klien. Tetapkan logLevel ke NOTICE untuk mulai mengambil log error mendetail.

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

Lihat panduan logging library klien PHP untuk mengetahui petunjuknya.

Python

Anda dapat menetapkan konfigurasi logging di file google-ads.yaml library klien. Tetapkan tingkat logging ke DEBUG untuk mulai mengambil log error mendetail.

Lihat panduan logging library Python untuk mengetahui opsi tambahan.

Ruby

Anda dapat menetapkan konfigurasi logging di file google_ads_config.rb library klien. Tetapkan tingkat logging ke INFO untuk mulai mengambil 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 menemukan error, berikut langkah-langkah yang harus dilakukan:

  1. Tangkap pengecualian dan ambil log: Mulai dengan menangkap pengecualian dan secara opsional mengambil log API.
  2. Periksa daftar errors: Lihat setiap GoogleAdsError dalam objek GoogleAdsFailure. The error_code dan message akan memberi tahu Anda apa yang salah.
  3. Periksa nilai location: Kolom location dapat membantu Anda menentukan lokasi masalah dalam permintaan.
  4. Lihat dokumentasi: Untuk kode error tertentu, periksa halaman error umum atau referensi kode error lengkap untuk mengetahui detail selengkapnya tentang error dan cara memperbaikinya.
  5. Sesuaikan permintaan Anda: Berdasarkan pesan error, perbaiki permintaan API Anda. Misalnya, jika Anda melihat REQUIRED_FIELD_MISSING, pastikan Anda memberikan kolom tersebut dalam permintaan Anda.
  6. Catat request_id: Jika Anda tidak dapat mengetahui cara mengatasi error dan perlu menghubungi dukungan), sertakan log permintaan dan respons lengkap untuk permintaan yang gagal. Pastikan untuk menyertakan the request_id. ID ini membantu teknisi 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 yang sering terjadi dan solusinya.
  • Untuk mengetahui teknik penanganan error yang lebih canggih, termasuk logika percobaan ulang dan kegagalan sebagian, lihat Memahami Error API.
Sebelumnya
Panduan memulai
Berikutnya
Error yang biasa terjadi