Hatalar

Tüm hata yanıtları ortak bir JSON zarfını paylaşır:

{ "message": "Okunabilir, yerelleştirilmiş mesaj.", "code": "opsiyonel_kod" }

message, aktif dile göre yerelleştirilir (bkz. Yerelleştirme). code isteğe bağlı, makine tarafından okunabilir bir tanımlayıcıdır.

Doğrulama hataları (422)

Doğrulama hataları, alan-anahtarlı bir errors haritası ekler (Laravel uyumlu):

{
  "message": "Verilen veri geçersiz.",
  "errors": {
    "email": ["E-posta alanı zorunludur."],
    "password": ["Parola en az 8 karakter olmalıdır."]
  }
}

Durum kodları

Durum	Anlamı
400	Hatalı biçimli istek
401	Kimlik doğrulanmadı
403	Doğrulandı ama izin yok (RBAC / policy / çapraz-kiracı)
404	Bulunamadı veya geçerli kiracıya görünür değil
419	CSRF token eksik/süresi dolmuş (SPA akışı) — /sanctum/csrf-cookie'yi yeniden çek
422	Doğrulama başarısız (yukarıya bakın)
429	Hız sınırı aşıldı (bkz. Hız Sınırlama)
5xx	Sunucu hatası (Sentry'ye raporlanır)

Kiracı izolasyonu ve 404

Çapraz-kiracı erişimi varlık bilgisi sızdırmaz: başka bir kiracıya ait bir kaynak Row Level Security altında görünmez ve 403 değil 404 döner.

İstek kimliği (hata ayıklama)

Her API yanıtı bir X-Request-Id başlığı taşır. Bu değer, ilgili isteğin tüm yapısal log satırlarına da (request_id) eklenir; dolayısıyla bu kimliği paylaşmak, isteğinizi sunucu loglarıyla ilişkilendirmemizi sağlar.

Kendi ilişkilendirme kimliğinizi X-Request-Id istek başlığıyla gönderebilirsiniz (harf/rakam, nokta, alt çizgi ve tire; en çok 128 karakter); göndermezseniz sunucu bir tane üretir. Bir sorun bildirirken, başarısız yanıttaki X-Request-Id değerini ekleyin.

Güvenlik başlıkları

API yanıtları temel güvenlik başlıkları içerir (X-Content-Type-Options, X-Frame-Options, Referrer-Policy, muhafazakâr bir Content-Security-Policy ve HTTPS üzerinde Strict-Transport-Security). Bunlar savunma amaçlıdır ve normal istemci kullanımını etkilemez.