Hatalar

Hata zarfı

Her uygulama route’u — bir uygulama token’ı ile çağırdığınız her şey — bir hatayı tek bir biçimde bildirir:

{
  "error": {
    "code": "missing_scope",
    "message": "This operation requires the write_products scope.",
    "scope": "write_products",
    "request_id": "0HN7…"
  }
}

Alan	Anlamı
code	Kararlı, makinece okunabilir bir tanımlayıcı. message’a değil bu alana göre dallanın.
message	İnsan için bir açıklama. İfadesi değişebilir; ayrıştırmayın.
scope	Yalnızca missing_scope durumunda: işlemin gerektirdiği scope.
request_id	Destek ile iletişime geçerken belirtin — isteği kayıtlarımızda bulmamızı sağlar.

Tek istisna, bunun yerine RFC 6749’u izleyen token endpoint’idir: {"error":"invalid_client","error_description":"…"}. Bkz. kimlik bilgileri ve token’lar.

Bazı route’lar, reddin bir zarfın taşıyamayacağı ayrıntı içerdiği durumlarda kendi tipli red gövdesini de korur — örneğin metaobject toplu istek düzeyi redleri ({ "code", "error" }) ve satır başına sonuçları. Bunlar route’un kendi sayfasında belgelenmiştir.

Hata kodları

Durum	code	Anlamı	Ne yapmalı
400	invalid_request	İstek hatalı biçimlendirilmiş ya da belgelenmiş bir sınırı aşıyor.	İsteği düzeltin. Değiştirmeden yeniden denemeyin.
400	idempotency_key_required	Route bir Idempotency-Key ister ve hiç (ya da boş) gönderilmedi.	Bir tane gönderin. Bkz. idempotency.
401	invalid_token	Token eksik, bilinmiyor, süresi dolmuş veya iptal edilmiş; kurulum kaldırılmış ya da uygulama askıya alınmış. WWW-Authenticate: Bearer error="invalid_token" taşır.	Bir kez yeni token alın. O da başarısız olursa durun ve uyarı verin — kurulum artık yok ya da devre dışı.
401	tenant_not_active	Mağazanın kendisi aktif değil.	Yeniden denemeyin. Tüccara bildirin.
403	wrong_store	Token, çağırdığınız alan adından farklı bir mağaza için verilmiş.	Token’ın ait olduğu mağazayı çağırın ya da kimlik bilgilerini bu mağazanın alan adında değiştirin.
403	missing_scope	Kurulumunuzda bu işlemin gerektirdiği scope (yetki) yok; scope onu belirtir. WWW-Authenticate: Bearer error="insufficient_scope" taşır.	Tüccardan bu izni vermesini isteyin.
404	not_found	Kayıt bu mağazada yok. Başka bir mağazaya ait kayıt her zaman 404 döner, asla 403 değil.	—
409	conflict	İstek, kaydın mevcut durumuyla çakışıyor.	Kaydı yeniden okuyun ve karar verin.
409	idempotency_in_progress	Bu anahtara sahip idempotent bir istek hâlâ çalışıyor. Retry-After: 1 taşır.	Bekleyin, sonra aynı anahtarla yeniden deneyin.
409	idempotency_unreplayable	Orijinal istek başarılı oldu, ancak yanıtı saklanamayacak kadar büyüktü.	Yeniden denemeyin; iş yapıldı.
413	payload_too_large	Gövde route’un boyut sınırını aşıyor.	İsteği bölün.
415	unsupported_media_type	Content-Type, route’un kabul ettiği türlerden değil.	application/json gönderin.
422	validation_failed	Gövde geçerli biçimde ama bir değer reddedildi.	Değeri düzeltin; message hangisi olduğunu söyler.
422	idempotency_key_reuse	Bu Idempotency-Key zaten farklı bir istekle kullanılmış.	Yeni bir istek için yeni bir anahtar kullanın.
429	rate_limited	Kurulumun istek bütçesi tükendi. Retry-After taşır.	Retry-After saniye kadar bekleyin. Bkz. rate limit’ler.
503	provider_unavailable	İşlemin bağlı olduğu bir servis kullanılamıyor.	Backoff ile yeniden deneyin.
5xx	internal_error	Bir platform hatası. İç ayrıntılar asla dahil edilmez.	Backoff ile yeniden deneyin; idempotent yazmaları yeniden denemek güvenlidir.

Toplu route’larda kısmi başarı normaldir

Toplu route’lar — toplu ürün güncellemeleri ve medya içe aktarımları — istek geçerli olduğunda 200 döner ve her satırı ayrı ayrı raporlar. failed: 3 içeren bir 200, üç satırın uygulanmadığı anlamına gelir. Satır başına status değerini her zaman okuyun.