Hata türleri

Hataları aşağıdaki genel kategorilere ayırdık:

  • Kimlik doğrulama
  • Yeniden denenebilecek hatalar
  • Doğrulama
  • Senkronizasyonla ilgili

Bu kategoriler olası tüm hataları kapsamaz ve bazıları birden fazla kategoriye sığabilir ancak uygulamanızın hata işleme yapısını oluşturmak için başlangıç noktası olarak kullanılabilir. Belirli hatalar hakkında daha fazla bilgi için aşağıdaki kaynaklara bakın:

  • Sık karşılaşılan hatalar bölümünde belirli bir hata hakkında daha fazla bilgi verilmektedir.
  • google.rpc.Status, API tarafından kullanılan mantıksal hata modeli hakkında ayrıntılı bilgi sağlar.
  • Standart hata kodları, Google Ads API bağlamında gRPC ve HTTP tarafından tanımlanan standart hata kodlarının listesini ve açıklamasını sağlar.

Kimlik doğrulama hataları

Kimlik doğrulama, uygulamanıza bir kullanıcı tarafından Google Ads'e kendi adına erişme izni verilip verilmediğini ifade eder. Kimlik doğrulama, OAuth2 akışı tarafından oluşturulan kimlik bilgileri aracılığıyla yönetilir.

Kimlik doğrulama hatasının kontrolünüz dışındaki faktörlerden kaynaklanmasının en yaygın nedeni, kimliği doğrulanmış kullanıcının uygulamanıza kendi adına işlem yapması için verdiği izni iptal etmesidir. Örneğin, uygulamanız bağımsız müşteriler için ayrı Google Ads hesapları yönetiyorsa ve her müşterinin hesabını yönetirken ayrı ayrı kimlik doğrulaması yapıyorsa müşteriler diledikleri zaman uygulamanızın erişimini iptal edebilir. Erişiminizin ne zaman iptal edildiğine bağlı olarak API doğrudan AuthenticationError.OAUTH_TOKEN_REVOKED hatası döndürebilir veya istemci kitaplıklarındaki yerleşik kimlik bilgisi nesneleri, iptal edilmiş jeton istisnası oluşturabilir. Her iki durumda da uygulamanızda müşterileriniz için bir kullanıcı arayüzü varsa uygulamanızın müşterileriniz adına işlem yapma iznini yeniden oluşturmak için müşterilerinizden OAuth2 akışını yeniden başlatmalarını isteyebilir.

Benzer şekilde, Google Cloud projenizin yalnızca Test erişim düzeyi varsa ve üretim (test dışı) hesabına istek göndermeye çalışırsa API, enum değeri API sürümüne bağlı olan bir AuthorizationError döndürür:

Yeniden denenebilecek hatalar

TRANSIENT_ERROR veya INTERNAL_ERROR gibi bazı hatalar, kısa bir süre bekledikten sonra isteği yeniden deneyerek çözülebilecek geçici bir sorunu gösterebilir.

Kullanıcı tarafından başlatılan isteklerde, kullanıcı arayüzünüzde hemen bir hata göstermek ve kullanıcıya yeniden deneme seçeneği sunmak bir stratejidir. Alternatif olarak, uygulamanız önce isteği otomatik olarak yeniden deneyebilir ve yalnızca maksimum yeniden deneme sayısına veya toplam kullanıcı bekleme süresine ulaştıktan sonra kullanıcı arayüzünde hatayı gösterebilir.

Arka uçta başlatılan istekler için uygulamanız, isteği otomatik olarak maksimum sayıda yeniden denemelidir.

İstekleri yeniden denerken rastgele gecikme içeren bir eksponansiyel geri yükleme politikası kullanın. Örneğin, ilk yeniden denemeden önce 5 saniye duraklatırsanız ikinci denemeden sonra 10 saniye, üçüncü denemeden sonra ise 20 saniye duraklatabilirsiniz. Senkronize yeniden deneme artışlarını önlemek için her aralığa küçük bir rastgele gecikme ekleyebilirsiniz. Eksponansiyel geri yükleme, API'yi çok agresif bir şekilde çağırmamanızı sağlar. Yeniden deneme sayısı tükendikten sonra hata devam ederse sorun giderme için yanıttaki request-id değerini günlüğe kaydedin.

Doğrulamayla ilgili hatalar

Doğrulama hataları, bir işleme yapılan girişin kabul edilemez olduğunu gösterir. Örnekler arasında PolicyViolationError, DateError, DateRangeError, StringLengthError ve UrlFieldError yer alır.

Doğrulama hataları en çok, kullanıcının geçersiz giriş yaptığı kullanıcı tarafından başlatılan isteklerde ortaya çıkar. Bu gibi durumlarda, aldığınız belirli API hatasına göre kullanıcıya uygun bir hata mesajı göstermeniz gerekir. Ayrıca, API çağrısı yapmadan önce kullanıcı girişini yaygın hatalar açısından doğrulayarak uygulamanızın daha duyarlı ve API kullanımınızın daha verimli olmasını sağlayabilirsiniz. Arka uçtan gelen istekler için uygulamanız, başarısız işlemi bir operatörün incelemesi için sıraya ekleyebilir.

Birçok Google Ads uygulaması, Google Ads nesnelerini depolamak için yerel bir veritabanı kullanır. Bu yaklaşımın zorluklarından biri, yerel veritabanının Google Ads'deki gerçek nesnelerle senkronizasyonunun bozulabilmesidir. Örneğin, bir kullanıcı doğrudan Google Ads'de bir reklam grubunu silebilir ancak uygulama ve yerel veritabanı bu değişiklikten haberdar olmaz ve reklam grubu mevcutmuş gibi API çağrıları yapmaya devam eder. Bu senkronizasyon sorunları, DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD gibi çeşitli hatalar olarak ortaya çıkabilir.

Kullanıcı tarafından başlatılan isteklerde, kullanıcıyı olası bir senkronizasyon sorunu konusunda uyarmak, ilgili Google Ads nesneleri sınıfını alan ve yerel veritabanını güncelleyen bir işi hemen başlatmak ve ardından kullanıcıdan kullanıcı arayüzünü yenilemesini istemek bir stratejidir.

Arka uç isteklerinde bazı hatalar, uygulamanızın yerel veritabanınızı otomatik ve aşamalı olarak düzeltmesi için yeterli bilgi sağlar. Örneğin, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD uygulamanızın bu reklamı yerel veritabanınızda kaldırıldı olarak işaretlemesine neden olur. Bu şekilde işleyemediğiniz hatalar, uygulamanızın daha kapsamlı bir senkronizasyon işi başlatmasına veya bir operatörün incelemesi için sıraya eklenmesine neden olabilir.

Sonraki
API hatalarını anlama