Hata kodları

Listings API HTTP durum kodları, Listings ve Social için SYxxxxx hata kodları ve v4 API'nin döndürdüğü üç hata yanıtı biçimi.

Listings API, bir isteğin sonucunu bildirmek için standart HTTP durum kodlarını kullanır. Hata kodları SY önekiyle başlar ve hata message dizesi içinde SYxxxxx: <human-readable reason> biçiminde iletilir.

HTTP durum kodları

Üç yanıt biçimi

Çoğu hata, aşağıdaki bölümlerde gösterildiği gibi en üst düzeyde veya işlemin sonucunun içinde iç içe yer alan bir errors dizisi içerir. Bazı hatalar ise bunun yerine tek bir error nesnesi döndürür: hız sınırlaması (429) ve bazı istek düzeyindeki hatalar (INTERNAL_SERVER_ERROR gibi bir code içeren 400/500). Her iki biçimi de kontrol edin: errors bir dizidir, error bir nesnedir.

1. İstek düzeyi: en üst düzeyde errors[]

Kimlik doğrulama, yetkilendirme ve hatalı biçimlendirilmiş istek hataları, işlem çalıştırılmadan önce akışı sonlandırır. Hatayı yanıtın en üst düzeyinde içeren, ilgili 4xx durumunu (yukarıda) döndürürler.

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. Yazma doğrulaması: iç içe data.<operation>.errors[]

Diğer açılardan doğru biçimlendirilmiş bir oluşturma, güncelleme veya yayımlama isteği HTTP 200 döndürür. Girdi bir iş kuralını ihlal ederse hata, işlemin kendi veri yükünün altında data.<operation>.errors içinde iç içe bildirilir. İşlem başarılı olduğunda bu dizi mevcuttur ve boştur ("errors": []).

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. Ağ geçidi düzeyi: en üst düzeyde tek bir error nesnesi

Hız sınırlaması ve beklenmeyen ağ geçidi hataları, dönüştürme işleminden önce akışı sonlandırır ve bir code, bir message ve bir correlation_id içeren tek bir error nesnesi döndürür. 429 gövdesi için aşağıdaki rate_limited bölümüne bakın.

Bir yazma işleminde, dolu bir data.<operation> nesnesi içeren 200 durumunda bile her zaman data.<operation>.errors değerini okuyun: yazma işlemi kısmen başarısız olabilir ve bunu burada bildirebilir.

402 Payment Required yanıtında error sarmalayıcısı bulunmaz: code, message, doc_url ve ödenecek bir fatura olduğunda pay_url en üst düzeydedir. Aşağıdaki payment_required bölümüne bakın.

Bir yazma işlemini yeniden denemek bedelsiz değildir

v4 API, Idempotency-Key desteği sunmaz: üst bilgi yok sayılır ve hiçbir uç nokta tekrarlanan yazma işlemlerini algılamaz. Zaman aşımına uğrayan veya 5xx döndüren bir oluşturma, güncelleme veya yayımlama çağrısı yine de sunucuda kalıcı olarak kaydedilmiş olabilir; bu nedenle kontrol etmeden yeniden denemek yinelenen bir konum, gönderi veya yorum yanıtı oluşturabilir.

Okuma işlemlerini bekleme süresini kademeli olarak artırarak serbestçe yeniden deneyin. Bir yazma işleminde önce veriyi geri okuyun: kaydı kontrolünüzdeki bir anahtarla (storeId, bir mağaza kodu, etkileşimin yanıt listesi) arayın ve yalnızca kayıt gerçekten mevcut değilse çağrıyı tekrarlayın.

Yaygın kodlar

SY10xxx aralığındaki doğrulama kodları belirli bir girdi alanına karşılık gelir; message, alanın veya karşılanmayan kuralın adını belirtir. SY90xxx aralığındaki kimlik doğrulama ve yetkilendirme kodları istek düzeyindedir ve eşleşen durumla birlikte en üst düzeyde gelir.

Bağlı hesap kodları

SY810xx aralığındaki kodlar, bir yayın platformundaki işletme kaydını içe aktaran veya bağlayan Connected Accounts uç noktalarından gelir. Bu kodlar, HTTP 200 yanıtının gövdesinde iç içe gelir (yukarıdaki 2. yanıt yapısı); bu nedenle durum başarılı olsa bile data.<operation>.errors değerini okuyun.

Social kodları

SY950xx aralığındaki kodlar Social endpoint'lerinden gelir: markalar, bağlantılar ve sosyal medya gönderileri. Bağlı hesap kodları gibi, bunlar da bir HTTP 200 yanıtının gövdesinde iç içe gelir; bu nedenle durum başarılı olsa bile data.<operation>.error değerini (ve toplu işlem rotalarında data.<operation>.errors değerini) okuyun.

SY95042 ve SY95044, girdi hataları değil, planın sağladığı haklarla ilgili hatalardır: planı değiştirmeden yeniden denemek aynı şekilde başarısız olur. SY95045, SY95046, SY95049 ve SY95052, sonraki istekte düzeltilebilen girdi hatalarıdır.

İşletme kaydı kullanım hakkı kodları

rate_limited

429 Too Many Requests: Hesap, planının istek hızı sınırını aştı. Gövde, bir retry_after_seconds ipucu, destek taleplerinde belirtmeniz için bir correlation_id ve bu bölüme geri bağlantı veren bir doc_url içeren standart hata yanıtıdır:

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

retry_after_seconds ile belirtilen süre boyunca (veya varsa Retry-After üst bilgisinde belirtilen süre boyunca) bekleyin, ardından bekleme süresini üstel olarak artırarak yeniden deneyin. Plan başına sınırlar ve örnek bir bekleme süresi artırma uygulaması için İstek hızı sınırları bölümüne bakın.

payment_required

402: Bu hesabın son ödemesi gerçekleşmediğinden tüm /api/v4 uç noktaları duraklatılmış durumda. Gövde, mevcut olduğunda, ödenmemiş faturanın Stripe sayfası olan pay_url bilgisini içerir ve X-Error-Code yanıt üst bilgisi aynı code bilgisini taşır. Ödeme yapmak için kontrol panelindeki Faturalandırma sayfasını hâlâ açabilirsiniz.

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

Son açık fatura ödendikten sonra erişim bir dakika içinde yeniden sağlanır. İlk başarısız ödemeden 3 gün sonra fatura hâlâ ödenmemişse Listings aboneliği iptal edilir ve hesabın konumları arşivlenir. Hesabın etkin bir Social aboneliği de varsa Social erişimi korunur; aksi takdirde hesap kapatılır ve API anahtarları çalışmayı durdurur.

social_payment_required

402: Social aboneliğinin son ödemesi gerçekleşmediğinden Social uç noktaları (/api/v4/social/*) duraklatılmış durumda. Listings uç noktaları çalışmaya devam eder. Gövde, payment_required ile aynı alanları içerir ve "code": "social_payment_required" bilgisine sahiptir. İlk başarısız ödemeden 3 gün sonra fatura hâlâ ödenmemişse Social aboneliği iptal edilir ve hesabın markaları arşivlenir. Listings aboneliği olmayan bir hesap kapatılır ve API anahtarları çalışmayı durdurur.

Geliştirici portalı kontrol düzlemi hataları

Geliştirici portalındaki hesap ve anahtar yönetimi uç noktaları (kontrol panelinin kendi API yolları), yukarıdaki REST errors[] biçimlerinden farklı, tek bir yapılandırılmış hata yanıtı döndürür. Her code, bir correlation_id ve burada ilgili bölüme geri bağlantı veren bir doc_url içerir.

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

auth_missing_key

401: Kimlik bilgileri sağlanmadı. Yeniden oturum açın veya anahtarınızı Authorization: API <your-key> olarak gönderin.

auth_invalid_key

401: Oturum veya anahtar geçersiz ya da süresi dolmuş. Yeniden kimlik doğrulaması yapın veya kontrol panelinden yeni bir anahtar oluşturun.

auth_insufficient_scope

403: Kimlik bilgileri geçerli ancak bu işlem için yetkili değil. Okuma yetkisi kapsamındaki bir anahtar yazma uç noktalarını çağıramaz; gerekiyorsa yazma yetkili bir anahtar oluşturun.

not_found

404: İstenen kaynak veya ID ile belirtilen bir kaynak mevcut değil.

conflict

409: İstek, kaynağın mevcut durumuyla çakışıyor (örneğin, zaten iptal edilmiş bir anahtarın iptal edilmesi).

validation_failed

422: İstek gövdesi doğrulamadan geçemedi. Yanıttaki field ve details, hataya neden olan girdiyi belirtir.

internal_error

500: Sunucu tarafında beklenmeyen bir hata oluştu. Okuma işlemini, bekleme süresini üstel olarak artırarak yeniden deneyin; yazma işlemi için önce kaydı yeniden okuyun (Yazma işlemini yeniden denemek bedelsiz değildir bölümüne bakın). Destek ekibiyle iletişime geçerseniz correlation_id bilgisini belirtin.

dependency_unavailable

503: API'nin bağımlı olduğu bir hizmet geçici olarak kullanılamıyor. Bekleme süresini artırarak yeniden deneyin.

429 için yukarıdaki rate_limited bölümüne bakın.

Kodda hataları işleme

Önce HTTP durumunu kontrol edin; ardından yazma işlemleri için yanıt gövdesinde iç içe bir errors dizisi arayın:

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

Doğrudan HTTP API kullanıldığında aynı iki kontrol açıkça yapılır: önce durum kodu, ardından yanıt içeriği kontrol edilir:

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

Python SDK her ikisini de sizin için yapar: her HTTP durumunu belirli bir türdeki istisnayla eşleştirir ve ayrıca bir 200 gövdesi içinde döndürülen hata içerikleri için de istisna oluşturur.