Hata Kodları

API yanıtlarında standart HTTP durum kodları kullanılmaktadır. Hata durumlarında yanıt gövdesi tutarlı bir yapıda döner.

Yanıt Yapısı

{
  "error": "Unauthorized",
  "message": "Invalid credentials"
}

Doğrulama (validation) hatalarında, hatalı item'ları detaylandıran bir errors dizisi yer alır:

{
  "errors": [
    { "index": 0, "barcode": "ABC", "message": "quantity must be int 0..9999" },
    { "index": 2, "barcode": "DEF", "message": "barcode is required (1-100 chars)" }
  ]
}

HTTP Durum Kodları

Sıkça Karşılaşılan Hatalar

401 — Invalid credentials

{"error": "Unauthorized", "message": "Invalid credentials"}

API anahtarı veya secret değeri hatalıdır. Anahtarın status=1 (aktif) durumda olduğundan emin olunmalıdır.

403 — SellerId does not match credentials

{"error": "Forbidden", "message": "SellerId does not match credentials"}

URL'de belirtilen sellerId ile API anahtarının sahibi olan kullanıcı eşleşmemektedir. İstek, anahtarın ait olduğu sellerId üzerinden yapılmalıdır.

403 — Insufficient scope

{"error": "Forbidden", "message": "Insufficient scope: stock:write"}

Çağrılan endpoint için gerekli yetki, API anahtarına tanımlanmamıştır. Yönetim panelinden ilgili scope eklenmelidir.

422 — Validation errors

{
  "errors": [
    { "index": 0, "barcode": "ABC123", "message": "quantity must be int 0..9999" }
  ]
}

Gönderilen item'lardan biri ya da birden fazlası kuralları karşılamamaktadır. Her hata kaydının index alanı, hangi item'a ait olduğunu belirtmektedir.

429 — Rate limit

{"error": "TooManyRequests", "message": "Rate limit exceeded"}

Dakikalık istek limiti aşılmıştır. Detaylı bilgi için Rate Limits sayfası incelenmelidir.

429 — Brute force lockout

{"error": "TooManyRequests", "message": "Too many failed authentication attempts. Try again later."}

Aynı IP adresinden 10 dakikalık zaman dilimi içerisinde 15'ten fazla başarısız kimlik doğrulama denemesi yapılmıştır. Bekleme süresi sonunda yeniden deneme yapılabilir.

Batch İçi Item Bazında Hatalar

Stok ve fiyat güncellemelerinde, batch içerisindeki bazı item'lar bireysel olarak başarısız olabilir. Bu durumda batch geneli completed durumuna geçer; ancak hatalı item'lar failed olarak işaretlenir:

{
  "batchRequestId": "abc-123",
  "status": "completed",
  "successCount": 8,
  "failureCount": 2,
  "items": [
    {
      "barcode": "XYZ",
      "status": "failed",
      "failureReasons": ["barcode not found for this seller"]
    }
  ]
}