Limitler ve Hatalar

İstek sınırları

Her API anahtarının iki sınırı vardır:

Sınır Değer Ne zaman sıfırlanır?
Dakikalık 60 istek Her takvim dakikasının başında (UTC)
Günlük 10.000 istek Her gün 00:00 UTC'de (Türkiye saatiyle 03:00)

Başarılı her yanıtta iki başlık bulunur:

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

X-RateLimit-Remaining, içinde bulunulan dakikada kalan istek sayısıdır. Sınır aşılırsa istek işlenmez ve 429 Too Many Requests döner:

HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
{
  "error": "Rate limit aşıldı. Dakika limiti: 60/dk. 18 saniye bekleyin.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 18
}

Retry-After başlığındaki saniye kadar bekleyip isteği tekrarlayın.

Çok sayıda ürünün stoğunu ya da fiyatını güncelliyorsanız her ürün için ayrı istek göndermeyin. Toplu Stok ve Fiyat ucu tek istekte 1.000 ürünü günceller ve dakikalık sınırı korur.

Hata yanıtları

Hatalı isteklerde gövde JSON'dur. Her hata yanıtında okunabilir bir error metni bulunur. Çoğunda makinenin okuyacağı bir code değeri de vardır:

{ "error": "Bu stok kodu (sku) başka bir üründe kayıtlı.", "code": "SKU_EXISTS" }

Entegrasyonunuzu error metnine göre değil, HTTP durum koduna ve code değerine göre kurun. Metinler zamanla değişebilir.

HTTP Anlamı Ne yapmalı?
200, 201 İşlem tamamlandı —
400 Gönderilen veri hatalı ya da bir iş kuralına uymuyor error ve code değerine bakın. Aynı isteği değiştirmeden tekrarlamayın.
401 Anahtar yok, geçersiz ya da iptal edilmiş Kimlik Doğrulama sayfasına bakın
403 İzin yok, mağaza ya da modül kapalı Kimlik Doğrulama sayfasına bakın
404 Tek kayıt okuma uçlarında (GET .../{id}) kayıt bulunamadı ya da bu mağazaya ait değil. Yazma uçlarında bulunamayan kayıt 400 ve PRODUCT_NOT_FOUND / ORDER_NOT_FOUND ile döner. Kimliği (id) kontrol edin
409 Kayıt aynı anda başka bir işlemle değişti Kısa bir süre sonra tekrar deneyin
429 İstek sınırı aşıldı Retry-After kadar bekleyin
5xx Sunucu tarafında geçici bir sorun Artan aralıklarla (örneğin 2, 4, 8 saniye) en fazla birkaç kez tekrar deneyin

Doğrulama hataları

Zorunlu bir alan eksikse, JSON bozuksa ya da bir alanın türü yanlışsa (örneğin sayı yerine metin) 400 döner. Yanıtta code: "VALIDATION_ERROR" bulunur. Alan bazındaki iletiler errors nesnesindedir:

{
  "title": "Doğrulama Hatası",
  "status": 400,
  "detail": "'price' alanı için gönderilen değer okunamadı (beklenen türde değil).",
  "instance": "/api/v1/products",
  "error": "'price' alanı için gönderilen değer okunamadı (beklenen türde değil).",
  "code": "VALIDATION_ERROR",
  "errors": {
    "price": ["'price' alanı için gönderilen değer okunamadı (beklenen türde değil)."]
  }
}

JSON sözdizimi bozuksa ileti errors.body altında İstek gövdesi okunamadı: geçerli bir JSON değil. olur.

Sık görülen hata kodları

code Uç Anlamı
PRODUCT_NOT_FOUND Ürün uçları Ürün bu mağazada yok.
SKU_EXISTS Ürün açma/güncelleme Stok kodu başka bir üründe kayıtlı.
CATEGORY_NOT_FOUND, BRAND_NOT_FOUND Ürün, kategori Kategori ya da marka bu mağazaya ait değil.
INVALID_PRICE, INVALID_QUANTITY, INVALID_TAX_RATE Ürün, stok Negatif fiyat ya da stok; 0–100 dışında KDV oranı.
NAME_REQUIRED, NAME_TOO_LONG, SKU_TOO_LONG, BARCODE_TOO_LONG Ürün, kategori, marka Ad boş ya da alan çok uzun.
PRODUCT_STOCK_DERIVED Stok Paket ürünün stoğu bileşenlerinden hesaplanır, elle girilemez.
PRODUCT_STOCK_NOT_TRACKED Stok Dijital ürünlerde stok tutulmaz.
EMPTY_ITEMS, TOO_MANY_ITEMS Toplu stok/fiyat Kalem listesi boş ya da 1.000'den uzun.
ORDER_NOT_FOUND Sipariş uçları Sipariş bu mağazada yok.
INVALID_STATUS Sipariş durumu Tanınmayan durum değeri.
INVALID_STATUS_TRANSITION Sipariş durumu Sipariş şu anki durumundan istenen duruma geçemez.
PAYMENT_NOT_COMPLETED Sipariş durumu Kartla ödemesi tamamlanmamış sipariş ilerletilemez.

Tekrar gönderilebilen istekler

Ağ hatasında isteğin sunucuya ulaşıp ulaşmadığını bilemeyebilirsiniz. Hangi isteğin güvenle tekrarlanabileceği:

  • Stok ve toplu stok/fiyat: Gönderdiğiniz değer olduğu gibi yazılır, mevcut değere eklenmez. Tekrar göndermek sonucu değiştirmez.
  • Kategori ve marka açma: Aynı adla (aynı üst kategori altında) tekrar gönderilirse yeni kayıt açılmaz, mevcut kayıt döner.
  • Sipariş durumu: Sipariş zaten istenen durumdaysa istek başarılı döner ve müşteriye ikinci e-posta gitmez.
  • Ürün açma (POST /products): Kendiliğinden tekrarlanabilir değildir. Yeniden göndermeden önce ürünün açılıp açılmadığını GET /products?sku=... ile kontrol edin. Aynı stok koduyla ikinci ürün açılmaz, SKU_EXISTS döner.