API hatalarını anlama

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

Google Ads API, gRPC durum kodlarına dayalı olan standart Google API hata modelini izler. 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ı.

Standartlaştırma hata kodları

Google Ads API, gRPC ve HTTP tarafından tanımlanan bir dizi standart hata kodu kullanır. Bu kodlar, hata türüyle ilgili üst düzey bir gösterge sağlar. Sorunun temel doğasını anlamak için ö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 Yönerge
0 200 OK Hata yok; başarıyı 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. Daha fazla ayrıntı için hata mesajına veya ayrıntılarına bakın. Sunucu hatası olarak değerlendirin. Genellikle geri çekilme ile 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 sorunu (ör. hatalı biçimlendirilmiş kaynak adı veya geçersiz değer) gösterir. İstemci hatası: İstek parametrelerinizi inceleyin ve API koşullarını karşıladığından emin olun. Hata ayrıntıları genellikle hangi bağımsız değişkenin geçersiz olduğu ve nasıl olduğu hakkında bilgi verir. İsteği düzeltmek için bu ayrıntıları kullanın. İsteği düzeltmeden yeniden denemeyin.
4 504 DEADLINE_EXCEEDED İşlem tamamlanmadan son tarih geçti. 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ı varlıklar 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 kaynak oluşturmaktan kaçının. Kaynağı oluşturmaya çalışmadan önce kaynağın mevcut olup olmadığını kontrol edin.
7 403 PERMISSION_DENIED Arayan kullanıcının belirtilen işlemi gerçekleştirme izni yok. İstemci hatası: Google Ads hesabının kimlik doğrulama, yetkilendirme ve kullanıcı rollerini kontrol edin. İzinleri çözmeden yeniden denemeyin.
8 429 RESOURCE_EXHAUSTED Bir kaynak tükenmiş (örneğin, kotanızı aşmışsınız) veya bir sistem aşırı yüklenmiş olabilir. İstemci/sunucu hatası: Genellikle beklemeniz gerekir. Eksponansiyel geri yükleme uygulayın ve istek sıklığı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 gerekli durumda olmadığından işlem reddedildi. Örneğin, zorunlu bir alan eksik. İstemci hatası: İstek geçerli ancak durum yanlış. Ön koşul hatasını anlamak için hata ayrıntılarını inceleyin. Eyalet düzeltilmeden tekrar denemeyin.
10 409 ABORTED İşlem, genellikle işlem çakışması gibi 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ş. İstemci hatası: Aralığı veya dizini düzeltin.
12 501 UNIMPLEMENTED İşlem, API tarafından uygulanmamış veya 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ıyla ilgili sorunlar için genel bir hazır yanıttır. Sunucu hatası: Genellikle eksponansiyel geri yükleme ile yeniden denenebilir. Devam ederse sorunu bildirin.
14 503 UNAVAILABLE Hizmet şu anda kullanılamıyor. Bu durum büyük olasılıkla geçicidir. Sunucu hatası: Eksponansiyel geri yüklemeyle yeniden denemeniz önemle tavsiye edilir.
15 500 DATA_LOSS Kurtarılamaz veri kaybı veya bozulması. Sunucu hatası: Nadir. Ciddi bir sorunu gösterir. Tekrar denemeyin. Devam ederse sorunu bildirin.
16 401 UNAUTHENTICATED İstek geçerli kimlik doğrulama bilgilerine sahip değil. İstemci hatası: Kimlik doğrulama jetonlarınızı ve kimlik bilgilerinizi doğrulayın. Kimlik doğrulama sorununu düzeltmeden yeniden 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 ötesinde Status nesnesinin details alanında daha ayrıntılı hata bilgileri sağlar. Bu alan genellikle GoogleAdsFailure proto'sunu içerir. Bu proto, bağımsız GoogleAdsError nesnelerinin listesini içerir.

Her GoogleAdsFailure nesnesi şunları içerir:

  • errors: Her biri belirli bir hatayı ayrıntılandıran 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

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

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.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" }
            ]
          }
        }
      ]
    }
  ]
}

Bu örnekte, üst düzey INVALID_ARGUMENT öğesine rağmen GoogleAdsFailure ayrıntıları, soruna name ve description alanlarının neden olduğunu ve nedenini (sırasıyla REQUIRED ve TOO_SHORT) belirtir.

Hata ayrıntılarını bulma

Hata ayrıntılarına erişme şekliniz, standart API çağrıları, kısmi hata veya akış kullanıp kullanmadığınıza bağlıdır.

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

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

Kısmi hata

partial failure 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, yanıttaki GoogleAdsFailure, google.rpc.Status nesnesine yerleştirilir.

Toplu işler

Toplu işlemede, tek tek işlemlerle ilgili hataları, iş tamamlandıktan sonra toplu iş sonuçlarını alarak bulabilirsiniz. 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 simgesini 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.
  • Sonraki meta veriler: Hem başarılı hem de başarısız istekler için request-id gRPC yanıtının sonraki meta verilerinde kullanılabilir.
  • Yanıt üstbilgileri: Hem başarılı hem de başarısız istekler için request-id, başarılı akış istekleri hariç olmak üzere gRPC ve HTTP yanıt üstbilgilerinde de kullanılabilir.
  • SearchGoogleAdsStreamResponse: Akış isteklerinde her SearchGoogleAdsStreamResponse mesajı request_id alanı içerir.

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

Hata işleme ile ilgili en iyi uygulamalar

Esnek uygulamalar oluşturmak için aşağıdaki en iyi uygulamaları uygulayın:

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

  2. İstemci ve sunucu hatalarını ayırt edin:

    • İstemci hataları: INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED gibi kodlar. Bu tür hatalar, isteğin veya uygulamanızın durumu/kimlik bilgilerinde değişiklik yapılmasını gerektirir. Sorunu gidermeden isteği yeniden göndermeyin.
    • Sunucu hataları: UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN gibi kodlar. Bunlar, API hizmetiyle ilgili geçici bir soruna işaret eder.

  3. Yeniden deneme stratejisi uygulama:

    • Ne zaman yeniden denenmeli: 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ürelerle beklemek için eksponansiyel geri yükleme algoritması kullanın. Bu sayede, zaten stresli olan bir hizmetin aşırı yüklenmesi önlenir. Örneğin, önce 1 saniye, sonra 2 saniye, sonra 4 saniye bekleyin. Maksimum yeniden deneme sayısına veya toplam bekleme süresine ulaşana kadar bu şekilde devam edin.
    • Jitter: Birçok istemcinin aynı anda yeniden denediği "gürleyen kalabalık" sorununu önlemek için geri çekilme gecikmelerine küçük bir rastgele "jitter" miktarı ekleyin.

  4. Kapsamlı günlük kaydı: Özellikle istek kimliği olmak üzere tüm ayrıntıları içeren hata yanıtının tamamını kaydedin. Bu bilgiler, hata ayıklama ve gerekirse Google Destek Ekibi'ne sorun bildirme için gereklidir.

  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, "Bir hata oluştu" demek yerine "Kampanya adı zorunludur" veya "Sağlanan reklam grubu kimliği bulunamadı" diyebilirsiniz.

Bu yönergeleri uygulayarak Google Ads API'nin döndürdüğü hataları etkili bir şekilde teşhis edip işleyebilir, daha kararlı ve kullanıcı dostu uygulamalar oluşturabilirsiniz.