Skip to main content
Payven hata yanıtları RFC 9457 — Problem Details for HTTP APIs standardına uyar. Tüm hata response’larının body’leri 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.
Tekrar denerken aynı Idempotency-Key ile gönderin. Aynı işlemin iki kez oluşmasını engeller. Bkz. Idempotency.

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önen correlation_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.