Hata işleme

Listings API Python SDK için istisna hiyerarşisi, hata öznitelikleri, HTTP 200 yanıt gövdesi hataları, istemci tarafı doğrulama ve yeniden deneme rehberi.

Tüm istisnalar üst düzey listingsapi modülünden içe aktarılabilir.

İstisna hiyerarşisi

ListingsAPIError├── APIError                    API-reported failure: non-2xx, or an error payload in HTTP 200│   ├── AuthenticationError     401, or payload codes SY90005 / SY90001│   ├── PermissionDeniedError   403, or payload code SY90003│   ├── NotFoundError           404│   ├── ValidationError         400 / 422, mutation failures, client-side validation│   ├── RateLimitError          429, or payload code RATE_LIMITED (carries .retry_after)│   └── InternalServerError     5xx (safe to retry)└── APIConnectionError          network failure: DNS, connection refused, timeout

SDK'nin fırlatabileceği tüm istisnaları işlemek için ListingsAPIError, API'nin bildirdiği tüm hataları işlemek için APIError veya belirli durumları işlemek için ilgili alt sınıfı yakalayın.

İstisna öznitelikleri

APIError ve alt sınıfları şu öznitelikleri içerir:

APIConnectionError doğrudan ListingsAPIError sınıfından türetilir ve bu özniteliklerin hiçbirine sahip değildir; istisna mesajı ağ hatasını açıklar.

İstisnaları yakalama

import listingsapi client = listingsapi.ListingsAPI() try:  location = client.locations.retrieve(16808)except listingsapi.AuthenticationError as e:  print("Invalid API key:", e.code)except listingsapi.PermissionDeniedError as e:  print("Not allowed:", e.status_code)except listingsapi.NotFoundError as e:  print("No such location:", e.status_code)except listingsapi.ValidationError as e:  for err in e.errors:      print(err["code"], err["message"], err["context"])except listingsapi.RateLimitError as e:  print("Rate limited, retry in", e.retry_after, "seconds")except listingsapi.InternalServerError as e:  print("Server error (safe to retry):", e.status_code)except listingsapi.APIConnectionError as e:  print("Network failure:", e)except listingsapi.APIError as e:  print("Unexpected API error:", e.status_code, e.code, e.response_body)

HTTP 200 yanıtlarındaki hatalar

Platform bazen hataları bir 200 yanıtının gövdesinde bildirir. SDK her yanıtı inceler ve istisna fırlatır; böylece success bayraklarını kendiniz kontrol etmeniz veya errors dizilerini kendiniz taramanız gerekmez:

• Üst düzey errors[] gövdeleri koda göre eşleştirilir: SY90005 ve SY90001 için AuthenticationError, SY90003 için PermissionDeniedError, RATE_LIMITED için RateLimitError ve diğer tüm kodlar için APIError istisnası fırlatılır.
• success: false veya bir errors[] listesi içeren yazma yanıtları (oluşturma, güncelleme, arşivleme, gönderi yayımlama) ValidationError istisnasının fırlatılmasına neden olur.

Her iki durumda da status_code gerçek HTTP durumudur (genellikle 200), code ilk platform kodudur ve errors standart biçime dönüştürülmüş tüm girdileri içerir:

import listingsapi client = listingsapi.ListingsAPI() try:  result = client.locations.update({"id": 16808, "phone": "not-a-phone"})except listingsapi.ValidationError as e:  print(e.status_code)   # 200: the API accepted the request but rejected the mutation  print(e.code)          # first platform code, e.g. "SY10005"  for err in e.errors:      print(err["code"], err["message"], err["context"])

İstemci tarafında doğrulama

locations.add() ve gönderi yardımcıları (posts.create_announcement(), posts.create_event(), posts.create_offer(), posts.bulk_publish()) veri yüklerini yerel olarak doğrular ve herhangi bir ağ çağrısından önce ValidationError istisnasını fırlatır; böylece geçersiz bir veri yükü gönderip yanıt beklemek yerine işlem hemen açıklayıcı bir mesajla başarısız olur.

locations.add() için:

• name 2 ile 150 karakter arasında olmalıdır
• description en az 200 karakter olmalıdır
• sub_category_id zorunludur
• country_iso zorunludur
• hide_address=True koşulu sağlanmadıkça city zorunludur (hizmet bölgesi işletmeleri)

Gönderi yardımcıları için:

• name zorunludur ve location_ids boş olmamalıdır
• sites, GOOGLE, FACEBOOK kümesinin boş olmayan bir alt kümesi olmalıdır
• message zorunludur; site başına değer içeren bir dict olduğunda her hedef site için metin gereklidir
• cta_type ve cta_url birlikte sağlanmalıdır ve cta_type şu değerlerden biri olmalıdır: BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP, GET_OFFER
• Etkinlikler ve teklifler için title zorunludur

Yerel olarak fırlatılan bu hatalarda status_code, code ve response_body değerleri None olur ve errors boştur; str(e) bulunan tüm sorunları listeler:

import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.add(      name="Acme Dental",      description="Too short.",      sub_category_id=1432,      country_iso="US",      city="New York",  )except listingsapi.ValidationError as e:  print(e)  # Invalid location: description must be at least 200 characters (got 10)  print(e.status_code)  # None: raised before any network call

Otomatik yeniden denemeler

SDK, GET, HEAD ve OPTIONS için 429, 500, 502, 503 ve 504 durumlarında otomatik olarak yeniden dener (varsayılan olarak 2 yeniden deneme, 0.5 saniyelik üstel bekleme katsayısı, Retry-After dikkate alınır). Yazma işlemleri yeniden denenmez: POST veya DELETE bir kez gönderilir ve ilk hatada istisna fırlatılır. max_retries kurucu parametresiyle yapılandırın; bkz. Yapılandırma.

v4 API, Idempotency-Key desteğine sahip değildir ve tekrarlanan yazma işlemlerini algılamaz; bu nedenle zaman aşımına uğrayan veya 5xx döndüren bir yazma işlemi veriyi zaten kaydetmiş olabilir. Kontrol etmeden yeniden denemek ikinci bir konum, gönderi veya yorum yanıtı oluşturur. Bir yazma işlemini tekrarlamadan önce kaydı, kontrolünüzdeki bir anahtarla yeniden okuyun.

RateLimitError durumunda bekleme

Yerleşik yeniden denemelerden sonra da 429 hatası devam ederse RateLimitError.retry_after, sunucunun Retry-After değerini saniye cinsinden içerir (başlık yoksa None olur). Toplu işler için basit bir örnek:

import randomimport time import listingsapi client = listingsapi.ListingsAPI(max_retries=0)  # manual retry control def with_backoff(call, max_attempts=5):  for attempt in range(max_attempts):      try:          return call()      except listingsapi.RateLimitError as e:          if attempt == max_attempts - 1:              raise          if e.retry_after is not None:              delay = e.retry_after          else:              delay = min(2 ** attempt, 30) + random.random()          time.sleep(delay) page = with_backoff(lambda: client.locations.list(first=50))for location in page:  print(location.name)

İstisnaları içe aktarma

# All exceptions from the top-level moduleimport listingsapi listingsapi.ListingsAPIErrorlistingsapi.APIErrorlistingsapi.AuthenticationErrorlistingsapi.PermissionDeniedErrorlistingsapi.NotFoundErrorlistingsapi.ValidationErrorlistingsapi.RateLimitErrorlistingsapi.InternalServerErrorlistingsapi.APIConnectionError # Or import individuallyfrom listingsapi import RateLimitError, ValidationError

Ayrıca bakınız

• Yapılandırma: max_retries ve timeout
• Hızlı başlangıç: hata işleme içeren ilk betiğiniz