Hata Kodları

API yanıtlarında standart HTTP durum kodları kullanılır. Hata durumunda yanıt gövdesi her zaman aynı yapıdadır: bir errors dizisi.

Yanıt Yapısı

Tüm hatalar aşağıdaki yapıyla döner. Tek bir hata olsa bile errors her zaman dizidir:

{
  "errors": [
    {
      "code": "Unauthorized",
      "message": "Invalid credentials"
    }
  ]
}

code Değerleri

Toplu Doğrulamada Farklı Hata Yapısı

Stok ve fiyat güncelleme ucu kalemleri tek tek doğruladığı için farklı bir 422 gövdesi döndürür. Burada errors dizisinin elemanlarında code bulunmaz; onun yerine hatalı kalemi işaret eden index ve barcode yer alır:

HTTP/1.1 422 Unprocessable Entity

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

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

401, Authentication required

{"errors":[{"code":"Unauthorized","message":"Authentication required"}]}

Authorization başlığı hiç gönderilmemiş. Yanıtta ayrıca WWW-Authenticate: Basic realm="Milagron API" döner.

401, Invalid credentials

{"errors":[{"code":"Unauthorized","message":"Invalid credentials"}]}

Anahtar veya parola hatalı, ya da anahtar pasif durumda. Anahtarın ortamı da bu hatayı verir: canlı ortam anahtarını başka bir ortamda kullanmak da aynı mesajı döndürür. Bilgi sızdırmamak için ayrı bir mesaj verilmez.

403, SellerId does not match credentials

{"errors":[{"code":"Forbidden","message":"SellerId does not match credentials"}]}

URL'deki sellerId, anahtarın sahibi olan mağazayla eşleşmiyor. İstek her zaman anahtarın kendi sellerId değeri üzerinden yapılmalıdır.

403, Insufficient scope

{"errors":[{"code":"Forbidden","message":"Insufficient scope: product:write"}]}

Uç için gereken yetki anahtarda tanımlı değil. Hangi ucun hangi yetkiyi istediği Kimlik Doğrulama sayfasındadır.

409, Barkod veya stok kodu çakışması

{"errors":[{"code":"Conflict","message":"A pending/created product already uses barcode BC123 or stockCode SKU123"}]}

Barkod veya stok kodu, yayındaki ya da onay bekleyen başka bir üründe kayıtlı. Barkodlar mağaza genelinde benzersiz olmalıdır.

422, Doğrulama hatası

{"errors":[{"code":"ValidationError","message":"title exceeds the maximum length (max 255 chars, got 312)"}]}

Mesaj, hangi alanın hangi limiti aştığını ve gönderdiğiniz değeri içerir. Varyant içindeki alanlarda sıra numarası belirtilir: variants[3].barcode is too long (max 100 chars). Tüm sınırlar için Limitler sayfasına bakın.

429, İstek limiti

{"errors":[{"code":"TooManyRequests","message":"Rate limit exceeded"}]}

Dakikalık istek limiti aşıldı. Yanıtta Retry-After, X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları döner. Ayrıntı için İstek Limitleri.

429, Güvenlik kilidi

{"errors":[{"code":"TooManyRequests","message":"Too many failed authentication attempts. Try again later."}]}

Aynı IP adresinden 10 dakika içinde 15 başarısız kimlik doğrulama denemesi yapıldı. 403 yanıtları da bu sayaca eklenir; yanlış sellerId ile döngüye giren bir entegrasyon kendini kilitleyebilir. Başarılı bir kimlik doğrulaması sayacı sıfırlar.

502, Ürün oluşturulamadı

{"errors":[{"code":"UpstreamError","message":"Product images could not be processed; check that every image url is publicly reachable and points directly to an image file"}]}

Ürün oluşturma, tüm adımları tamamlanmadan başarılı sayılmaz. Görsel adımı başarısız olursa oluşturulan ürün geri alınır ve hiçbir kayıt kalmaz. Aynı gövdeyle güvenle tekrar deneyebilirsiniz.

Toplu İşlemde Kalem Bazında Hatalar

Stok ve fiyat güncellemeleri asenkron çalışır. Doğrulamayı geçen bir işlemin içindeki bazı kalemler işlenirken tek tek başarısız olabilir. Bu durumda işlemin geneli completed olur, hatalı kalemler failed işaretlenir:

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

Hata İşleme Önerileri

• code ile dallanın, message ile değil. Mesaj metinleri önceden bildirilmeden iyileştirilebilir.
• errors[0].code yoksa gövde kalem bazlı bir toplu işlem hatasıdır; index alanını kullanın.
• 4xx hatalarını yeniden denemeyin. 400, 401, 403, 404, 409 ve 422 aynı istekle her zaman aynı sonucu verir. Düzeltmeden tekrar göndermek yalnızca istek hakkınızı ve güvenlik sayaçlarını tüketir.
• 429, 500, 502 ve 503 yeniden denenebilir. Denemeler arasındaki süreyi kademeli olarak artırın, 429 için Retry-After başlığına uyun.
• Asenkron uçlarda 200 son söz değildir. İşlemin sonucunu durum sorgulama ile doğrulayın.