application/problem+json MIME tipindedir; HTTP durum kodu kategoriyi, gövdedeki code alanı ise hatanın programatik tipini belirtir.
Hata yanıt formatı
HTTP kategorileri
Banka reddi de bir hata yanıtıdır. Gateway’e ulaşmış ama banka tarafında reddedilen
ödeme
422 Unprocessable Entity + application/problem+json ile döner; gövdede
code: "bank_declined" ve banka ham yanıt kodu (provider_error_code, örn. "51" —
yetersiz bakiye) yer alır. Sonuç değerlendirmesini yalnız HTTP durum kodu üzerinden
yapın.Yaygın hata kodları
Kimlik doğrulama / yetki
İstek formatı / validasyon
Validasyon hatalarında alan-bazlı detay
errors[] array’inde döner:
Ödeme / işlem kuralları
Yönlendirme ve banka
Idempotency / rate limit
Banka yanıt kodlarının ve konnektör hata mesajlarının tam listesi: Sanal POS → Hata Kodları.
Retry stratejisi
Sadece geçici hatalar için retry uygun:429, 5xx, network timeout. Idempotent olmayan işlemleri retry ederken mutlaka aynı Idempotency-Key kullanın — yoksa aynı işlem birden fazla yapılır.
Önerilen pattern: exponential backoff + jitter.
Müşteriye gösterme
detail alanı son kullanıcıya gösterilebilir nitelikte yazılır. Yine de hassas durumlarda (fraud, fraud-review, banka tarafı reddi) genel bir mesajla geçiştirmek daha güvenlidir:
Destek talebi açarken
Her hata yanıtında dönencorrelation_id değerini paylaşın — log zincirini saniyeler içinde bulabiliriz. Response header’ındaki X-Correlation-Id ile gövdedeki correlation_id aynı değerdir.