Hatalar ve Limitler - Hemen Mağaza Developers

Hata formatı

API hataları standart JSON formatında döner:

{
  "message": "İstek yetkilendirilemedi.",
  "code": "unauthorized"
}

Validasyon hatalarında alan bazlı açıklamalar bulunur:

{
  "message": "Gönderilen bilgiler geçersiz.",
  "errors": {
    "email": ["Geçerli bir e-posta adresi girin."]
  }
}

Kod	Anlamı	Ne yapmalısınız?
`400`	Geçersiz istek	Parametreleri kontrol edin.
`401`	Eksik veya hatalı token	Token header’ını ve key durumunu kontrol edin.
`403`	Yetki veya tenant uyuşmazlığı	Scope, origin ve tenant eşleşmesini kontrol edin.
`404`	Kayıt bulunamadı	ID, slug veya cart token doğru mu kontrol edin.
`422`	Validasyon hatası	Response içindeki `errors` alanını kullanıcıya gösterin.
`429`	Rate limit aşıldı	Kısa süre bekleyip tekrar deneyin.
`500`	Sunucu hatası	Request ID ile Hemen Mağaza ekibine iletin.

Rate limit uygulanan endpointlerde aşağıdaki header’lar dönebilir:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1760000000

Remaining değeri sıfıra yaklaşırsa yeni istekleri yavaşlatın.

429, geçici ağ hatası veya webhook delivery hatalarında exponential backoff kullanın:

deneme: hemen
deneme: 30 saniye sonra
deneme: 2 dakika sonra
deneme: 10 dakika sonra

Sipariş oluşturma gibi yazma operasyonlarında idempotency anahtarı kullanmanız önerilir.

Idempotency-Key: order-frontend-8f1f7c