API hatalarını anlama

Bu kılavuzda, Google Ads API'nin hataları nasıl işlediği ve ilettiği açıklanmaktadır. API hatalarının yapısını ve anlamını anlamak, geçersiz girişten geçici hizmet kesintisine kadar sorunları düzgün bir şekilde ele alabilen sağlam uygulamalar oluşturmak için çok önemlidir.

Google Ads API, gRPC durum kodlarını temel alan standart Google API hata modelini kullanır. Hatayla sonuçlanan her API yanıtı, aşağıdakileri içeren bir Status nesnesi içerir:

  • Sayısal bir hata kodu.
  • Hata mesajı.
  • İsteğe bağlı, ek hata ayrıntıları.

Standart hata kodları

Google Ads API, gRPC ve HTTP tarafından tanımlanan bir dizi standart hata kodu kullanır. Bu kodlar, hata türünün üst düzey bir göstergesini sağlar. Sorunun temel doğasını anlamak için her zaman önce bu sayısal kodu kontrol etmeniz gerekir.

Aşağıdaki tabloda, Google Ads API'yi kullanırken karşılaşabileceğiniz en yaygın kodlar özetlenmiştir:

gRPC kodu HTTP kodu Enum adı Açıklama Rehberlik
0 200 OK Hata yok; işlemin başarılı olduğunu gösterir. Yok
1 499 CANCELLED İşlem genellikle istemci tarafından iptal edildi. Genellikle istemcinin beklemeyi bıraktığı anlamına gelir. İstemci tarafı zaman aşımlarını kontrol edin.
2 500 UNKNOWN Bilinmeyen bir hata oluştu. Hata mesajında veya ayrıntılarda daha fazla bilgi olabilir. Sunucu hatası olarak değerlendirilir. Genellikle bekleme süresiyle yeniden denenebilir.
3 400 INVALID_ARGUMENT İstemci geçersiz bir bağımsız değişken belirtti. Bu, API'nin isteği işlemesini engelleyen bir sorun olduğunu gösterir (ör. hatalı biçimlendirilmiş kaynak adı veya geçersiz değer). İstemci hatası: İstek parametrelerinizi inceleyin ve API koşullarını karşıladıklarından emin olun. Hata ayrıntıları genellikle hangi bağımsız değişkenin geçersiz olduğu ve nasıl geçersiz olduğu hakkında bilgi verir. İsteği düzeltmek için bu ayrıntıları kullanın. İsteği düzeltmeden tekrar denemeyin.
4 504 DEADLINE_EXCEEDED İşlem tamamlanmadan önce son tarih sona erdi. Sunucu hatası: Genellikle geçicidir. Eksponansiyel geri yükleme ile yeniden denemeyi düşünebilirsiniz.
5 404 NOT_FOUND Kampanya veya reklam grubu gibi istenen bazı öğeler bulunamadı. İstemci hatası: Erişmeye çalıştığınız kaynakların varlığını ve kimliğini doğrulayın. Düzeltme yapmadan tekrar denemeyin.
6 409 ALREADY_EXISTS İstemcinin oluşturmaya çalıştığı öğe zaten mevcut. İstemci hatası: Yinelenen kaynaklar oluşturmaktan kaçının. Kaynağı oluşturmaya çalışmadan önce mevcut olup olmadığını kontrol edin.
7 403 PERMISSION_DENIED Arayanın, belirtilen işlemi yürütme izni yok. İstemci hatası: Google Ads hesabının kimlik doğrulama, yetkilendirme ve kullanıcı rollerini kontrol edin. İzinleri çözmeden tekrar denemeyin.
8 429 RESOURCE_EXHAUSTED Bir kaynak tükenmiş (örneğin, kotanızı aşmış olabilirsiniz) veya bir sistem aşırı yüklenmiş olabilir. İstemci/sunucu hatası: Genellikle beklemeniz gerekir. Eksponansiyel geri yükleme uygulayın ve istek hızını azaltın. API sınırları ve kotaları başlıklı makaleyi inceleyin.
9 400 FAILED_PRECONDITION Sistem, işlemin yürütülmesi için gereken durumda olmadığından işlem reddedildi. Örneğin, zorunlu bir alan eksik olabilir. İstemci hatası: İstek geçerli ancak durum yanlış. Ön koşul hatasını anlamak için hata ayrıntılarını inceleyin. Durum düzeltilmeden tekrar denemeyin.
10 409 ABORTED İşlem, genellikle işlem çakışması gibi bir eşzamanlılık sorunu nedeniyle iptal edildi. Sunucu hatası: Genellikle kısa bir bekleme süresinin ardından yeniden denemek güvenlidir.
11 400 OUT_OF_RANGE İşlem, geçerli aralığın dışında denenmiştir. İstemci hatası: Aralığı veya dizini düzeltin.
12 501 UNIMPLEMENTED İşlem uygulanmıyor veya API tarafından desteklenmiyor. İstemci hatası: API sürümünü ve kullanılabilir özellikleri kontrol edin. Tekrar denemeyin.
13 500 INTERNAL Dahili bir hata oluştu. Bu, sunucu tarafındaki sorunlar için genel bir hata mesajıdır. Sunucu hatası: Genellikle eksponansiyel geri yükleme ile yeniden denenebilir. Sorun devam ederse sorunu bildirin.
14 503 UNAVAILABLE Hizmet geçici olarak kullanılamamaktadır. Bu durum büyük olasılıkla geçicidir. Sunucu hatası: Eksponansiyel geri yükleme ile yeniden denemeniz önemle tavsiye edilir.
15 500 DATA_LOSS Kurtarılamayan veri kaybı veya bozulması Sunucu hatası: Nadir. Ciddi bir sorun olduğunu gösterir. Tekrar denemeyin. Sorun devam ederse sorunu bildirin.
16 401 UNAUTHENTICATED İstekte geçerli kimlik doğrulama bilgileri yok. İstemci hatası: Kimlik doğrulama jetonlarınızı ve kimlik bilgilerinizi doğrulayın. Kimlik doğrulama sorununu düzeltmeden tekrar denemeyin.

Bu kodlar hakkında daha fazla bilgi için API Tasarım Kılavuzu - Hata kodları başlıklı makaleyi inceleyin.

Hata ayrıntılarını anlama

Google Ads API, üst düzey kodun yanı sıra Status nesnesinin details alanında daha ayrıntılı hata bilgileri sağlar. Bu alan genellikle bağımsız GoogleAdsError nesnelerinin listesini içeren bir GoogleAdsFailure proto içerir.

Her GoogleAdsFailure nesnesi şunları içerir:

  • errors: Her biri, meydana gelen belirli bir hatayı ayrıntılı olarak açıklayan GoogleAdsError nesnelerinin listesi.
  • request_id: İstek için benzersiz bir kimlik. Hata ayıklama ve destek amaçları için kullanışlıdır.

Her GoogleAdsError nesnesi şunları sağlar:

Hata ayrıntıları örneği

Hata aldığınızda istemci kitaplığınız bu ayrıntılara erişmenize olanak tanır. Örneğin, bir INVALID_ARGUMENT (Kod 3) şu şekilde GoogleAdsFailure ayrıntılarına sahip olabilir:

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

Bu örnekte, üst düzey INVALID_ARGUMENT değerine rağmen GoogleAdsFailure ayrıntıları, soruna name ve description alanlarının neden olduğunu ve bunun sebebini (sırasıyla REQUIRED ve TOO_SHORT) gösterir.

Hata ayrıntılarını bulma

Hata ayrıntılarına nasıl erişeceğiniz, standart API çağrıları, kısmi hata veya akış kullanmanıza bağlıdır.

Standart ve akış API çağrıları

Kısmi hata kullanılmadan bir API çağrısı başarısız olduğunda (akış çağrıları dahil), gRPC yanıt başlıklarındaki sondaki meta verilerin bir parçası olarak GoogleAdsFailure nesnesi döndürülür. Standart çağrılar için REST kullanıyorsanız HTTP yanıtında GoogleAdsFailure döndürülür. İstemci kitaplıkları genellikle bunu GoogleAdsFailure özelliğine sahip bir istisna olarak gösterir.

Kısmi hata

Kısmi hata kullanıyorsanız başarısız işlemlerle ilgili hatalar, yanıt başlıklarında değil, yanıtın partial_failure_error alanında döndürülür. Bu durumda GoogleAdsFailure, yanıttaki bir google.rpc.Status nesnesine yerleştirilir.

Toplu işler

Toplu işleme için, iş tamamlandıktan sonra BatchJobService.ListBatchJobResults çağrılarak her bir işlemin hataları bulunabilir. Her işlem sonucu, işlem başarısız olursa hata ayrıntılarını içeren bir status alanı içerir.

Talep numarası

request-id, API isteğinizi tanımlayan benzersiz bir dizedir ve sorun giderme için gereklidir.

request-id numarasını birden fazla yerde bulabilirsiniz:

  • GoogleAdsFailure: Bir API çağrısı başarısız olursa ve GoogleAdsFailure döndürülürse request_id içerir.
  • Sondaki meta veriler: Hem başarılı hem de başarısız istekler için gRPC yanıtının sondaki meta verilerinde request-id bulunur.
  • Yanıt başlıkları: Başarılı ve başarısız istekler için request-id, başarılı akış istekleri hariç olmak üzere gRPC ve HTTP yanıt başlıklarında da kullanılabilir.
  • SearchGoogleAdsStreamResponse: Akış istekleri için her SearchGoogleAdsStreamResponse mesajı bir request_id alanı içerir.

Hataları günlüğe kaydederken veya destek ekibiyle iletişime geçerken sorunların teşhis edilmesine yardımcı olmak için request-id değerini eklediğinizden emin olun.

Hata işleme ile ilgili en iyi uygulamalar

Esnek uygulamalar oluşturmak için aşağıdaki en iyi uygulamaları hayata geçirin:

  1. Hata ayrıntılarını inceleyin: Status nesnesinin details alanını her zaman ayrıştırın ve özellikle GoogleAdsFailure değerini arayın. GoogleAdsError içindeki ayrıntılı error_code, message ve location, hata ayıklama ve kullanıcı geri bildirimi için en uygulanabilir bilgileri sağlar.

  2. İstemci hatalarını sunucu hatalarından ayırt etme:

    • İstemci hataları: INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED gibi kodlar. Bu hatalar, istekte veya uygulamanızın durumunda/kimlik bilgilerinde değişiklik yapılmasını gerektirir. Sorunu çözmeden isteği yeniden denemeyin.
    • Sunucu hataları: UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN gibi kodlar. Bu durum, API hizmetinde geçici bir sorun olduğunu gösterir.

  3. Yeniden deneme stratejisi uygulama:

    • Yeniden deneme zamanı: Yalnızca UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN ve ABORTED gibi geçici sunucu hataları için yeniden deneyin.
    • Eksponansiyel geri yükleme: Yeniden denemeler arasında artan süreler boyunca beklemek için eksponansiyel geri yükleme algoritması kullanın. Bu sayede, zaten yoğun olan bir hizmetin daha da yoğunlaşması önlenir. Örneğin, 1 saniye, ardından 2 saniye, ardından 4 saniye bekleyerek maksimum yeniden deneme sayısına veya toplam bekleme süresine ulaşana kadar devam edin.
    • Dalgalanma: Birçok istemcinin aynı anda yeniden deneme yapmasıyla ortaya çıkan "gök gürültüsü" sorununu önlemek için bekleme gecikmelerine küçük bir rastgele "dalgalanma" miktarı ekleyin.

  4. Ayrıntılı günlük kaydı: Tüm ayrıntılar, özellikle de istek kimliği dahil olmak üzere hata yanıtının tamamını günlüğe kaydedin. Bu bilgiler, hata ayıklama ve gerektiğinde sorunları Google Destek Ekibi'ne bildirme açısından önemlidir.

  5. Kullanıcı geri bildirimi sağlama: Belirli GoogleAdsError kodlarına ve mesajlarına göre uygulamanızın kullanıcılarına net ve faydalı geri bildirimler sağlayın. Örneğin, yalnızca "Bir hata oluştu" demek yerine "Kampanya adı gerekli" veya "Sağlanan reklam grubu kimliği bulunamadı" diyebilirsiniz.

Bu yönergeleri uygulayarak Google Ads API tarafından döndürülen hataları etkili bir şekilde teşhis edip ele alabilir, böylece daha kararlı ve kullanıcı dostu uygulamalar oluşturabilirsiniz.

Önceki
Hata türleri
Sonraki
Yaygın görülen hatalar