Hata Formatı

Laravel standart format kullanıyoruz. Accept: application/json header'ı her zaman ekleyin — eksikse hata HTML olarak dönebilir.

HTTP kodları

Kod	Anlam	Tipik senaryo
200	Başarılı	listele, güncelle, indirme
201	Oluşturuldu	yeni kayıt — response içinde id
202	Kuyruğa alındı	bulk import (POST /bulk-operations/import)
200	Silme başarılı	silme — JSON mesaj döner ({"message":"… silindi."})
400	Bozuk istek	JSON parse hatası
401	Kimliksiz	token eksik / geçersiz
403	Yasak	tenant izinsiz erişim veya abonelik/plan kısıtı (bkz. aşağıda)
404	Bulunamadı	id yok veya başka tenant'a ait
409	Çakışma	iş kuralı: duplicate mapping vs.
422	İşlenemez	validation — errors alanında detay
429	Çok fazla istek	rate limit (gelecekte)
500	Sunucu hatası	log'a düşer, retry edilebilir
503	Hizmet yok	DB down, queue full

Abonelik & plan hataları (403)

Tüm v1 uçları aboneliğe bağlıdır. Yetki/tenant hatasından ayrı olarak, gövdedeki code alanı kısıtı belirtir — entegratörün bunu ayırt etmesi gerekir:

code	Anlamı	Ne yapmalı
subscription_expired	Abonelik kilitli/süresi dolmuş — yazma işlemleri reddedilir	Operatör abonelik yenilemeli; retry etme
plan_limit_exceeded	Plan kotası aşıldı (örn. ürün limiti)	Plan yükseltilmeli; retry etme

{ "message": "Aboneliğinizin süresi doldu.", "code": "subscription_expired" }

Başlangıç planında API kapalı: api_access özelliği yalnız Pro/Kurumsal planlarda açıktır. Başlangıç planındaki bir hesabın API anahtarı v1 uçlarında 403 alır. GET /v1/me → subscription.plan_code / status ile durumu önceden kontrol edebilirsin.

Standart hata gövdesi

Validation hatası (422)

{
  "message": "Geçersiz KDV oranı: 18. Tanımlı oranlar: 0, 1, 10, 20",
  "errors": {
    "tax_rate": ["Geçersiz KDV oranı: 18. Tanımlı oranlar: 0, 1, 10, 20"]
  }
}

• message — okunabilir özet (ilk hatanın metni)
• errors — alan adı → mesaj array'i

Birden fazla alan hatalıysa hepsi errors içinde döner:

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "sku": ["Bu SKU ile başka bir ürün zaten var."]
  }
}

Genel hata (401, 403, 404, 500)

{"message": "Unauthenticated."}

500'lerde mesajı kullanıcıya gösterme — log'a yansır, retry öner.

Sık karşılaşılan validation mesajları

Alan	Mesaj	Çözüm
name	"The name field is required."	POST /products'ta name zorunlu
sku	"Bu SKU ile başka bir ürün zaten var."	farklı sku gönder veya mevcut ürünü güncelle
tax_rate	"Geçersiz KDV oranı: X. Tanımlı oranlar: 0, 1, 10, 20"	Sadece sistemdeki oranı kullan veya tax_rate_id ile gönder
brand_id	"Seçilen marka bulunamadı."	GET /brands ile valid ID öğren veya brand_name kullan
category_ids	"Seçilen kategorilerden bazıları bulunamadı."	GET /categories ile valid ID öğren veya category_paths kullan
image	"image must be one of: jpeg, jpg, png, webp"	sadece kabul edilen formatlar
image	"image may not be greater than 5120 kilobytes"	5MB altı

Retry stratejisi

• 422 → retry yapma, payload düzeltilmeli
• 401/403 → retry yapma, token sorunu
• 500/503 → exponential backoff (1s, 2s, 4s, 8s, 16s — max 5 deneme)
• Network timeout → retry yap ama idempotency için ileride Idempotency-Key header desteği eklenecek