Hata Sözleşmesi

Tüm hata ve iş uyarıları tek bir sözleşmeyle döner:

{
  "messageCode": "CONTRACT_STATE_INVALID",
  "severity": "ERROR",
  "params": {
    "contractId": "ctr_01J8ZK4T2M",
    "currentState": "TERMINATED",
    "attemptedAction": "APPROVE"
  },
  "traceId": "8f4a2c1e-9b3d-4e7f-a1c2-5d6e7f8a9b0c",
  "message": "Sözleşme mevcut durumunda bu işleme izin vermiyor."
}

Alan	Tip	Açıklama
`messageCode`	string	Makine tarafından okunabilir, kararlı kod. Entegrasyon mantığınızı bu alana kurun.
`severity`	`ERROR` \| `WARNING` \| `INFO`	İşlemin reddedildiğini mi, uyarıyla kabul edildiğini mi bildirir.
`params`	object	Koda bağlı yapısal parametreler; kendi mesajınızı üretmek için kullanın.
`traceId`	string	Uçtan uca izleme kimliği; destek taleplerinde paylaşın.
`message`	string	İnsan için hazır metin — istek dilindeki katalog karşılığı.

Üç dilli mesaj kataloğu

message alanı merkezi mesaj kataloğundan çözülür ve Türkçe, İngilizce ve Arapça olarak sunulur. Dil, Accept-Language başlığından seçilir (tr varsayılandır):

POST /api/v1/contracts HTTP/1.1
Accept-Language: en

Katalog yaklaşımının iki sonucu vardır:

Kanallar metin uydurmaz. Müşteri portalı, operasyon konsolu ve sizin entegrasyonunuz aynı messageCode için aynı metni gösterebilir.
Metin değişebilir, kod değişmez. Katalogdaki ifadeler iyileştirilebilir; messageCode değerleri kararlıdır ve sürüm taahhüdüne tabidir.

HTTP durum kodları

Durum	Anlamı
`400`	Biçimsel doğrulama hatası (eksik alan, geçersiz tip)
`401`	Kimlik doğrulama başarısız / jeton süresi dolmuş
`403`	Rol/yetki yetersiz
`404`	Kaynak bulunamadı (kiracı kapsamında)
`409`	İş kuralı çakışması (durum makinesi, dört göz, idempotans)
`422`	İş doğrulaması başarısız (ör. türetilen alan gönderilmiş)
`500`	Beklenmeyen hata — `traceId` ile bildirin