Hata Yönetimi

Cüzdan hataları üç soruya cevap verecek şekilde tasarlanmıştır: ne oldu, para hareket etti mi, yeniden denenebilir mi.

Hata sınıfları

Kimlik doğrulama hataları

s2s imza yüzeyinin hata kodları ve çözümleri Kimlik Doğrulama sayfasındadır: AUTH_HEADERS_MISSING, INVALID_DATE, NONCE_REPLAY, INVALID_KID, MERCHANT_SUSPENDED, IP_NOT_ALLOWED, DIGEST_MISSING, INVALID_DIGEST, INVALID_SIGNATURE. İmzadan sonra iki 403 reddi daha gelebilir: PRODUCT_NOT_ENABLED ve WALLET_INSUFFICIENT_SCOPE.

Fail-closed ne demek

Cüzdan, para yolunda belirsizliği reddeder:

Pratik sonuçları:

• Limit servisi yanıt vermiyorsa çıkış işlemi reddedilir.
• Kart otorizasyonunda limit yanıtı kısa bir son tarih içinde gelmezse otorizasyon reddedilir.
• Bağlı sağlayıcısı olmayan entegrasyonlar program yapılandırmasıyla kapalıdır; kapalı bir entegrasyonu çağırmak reddedilir (Yol Haritası).

Tek istisna, platform tabanında olmayan ve KYC eşiği hiç tanımlanmamış operasyon tipleridir: o kapı devreye girmez. Transfer, çekim, nakit ve kart işlemleri platform tabanındadır; kimliği doğrulanmamış kullanıcı için her programda reddedilir. Bkz. KYC Seviyeleri.

Yeniden deneme kuralları

Belirsiz sonuç: INDETERMINATE

Bir para işleminin sonucu o an kesinleştirilemiyorsa (ör. defter kaydı onaylandı mı bilinmiyorsa) cüzdan bunu bir hata olarak değil, status: "INDETERMINATE" olarak bildirir. Anlamı: para hareket etmiş olabilir, son durum henüz yazılmamıştır. Cüzdan işlemi kendiliğinden kesinleştirir (COMPLETED, FAILED ya da REVERSED).

Bu sonucu döndüren uçlar: cüzdanla ödeme onayı (Cüzdanla Ödeme) ve temsilci ile yükleme (Bakiye Yükleme).

Operasyon üzerindeki hata alanları

Başarısız bir operasyon, hatayı iki alanda taşır:

Kullanıcıya failureReason'ı ham hâliyle göstermeyin; kendi ürün diline çevirin. Destek ekibinize failureCode'u gösterin.

Dil

Hata mesajları Accept-Language header'ına göre döner (varsayılan Türkçe).

-H "Accept-Language: en"

Kullanıcıya hata gösterme

Yapılandırılmış details taşıyan hatalar

Bazı hatalar salt metin değildir: details altında makine tarafından okunabilir bir kırılım taşırlar. Bunları metinden ayrıştırmayın.

Program arşivleme (409)

..._IN_FLIGHT hatası details.inFlightByAxis (eksen → sayı), details.capped, details.probeCap ve eksen başına details.axes[] taşır. Dört eksen: OPERATION, CASHOUT_CODE, CARD_AUTHORIZATION, BULK_PAYOUT_BATCH.

Toplu içe aktarma / ayırma (422)

WALLET_BULK_IMPORT_REJECTED ve WALLET_BULK_OFFBOARD_REJECTED, satır satır raporu details altında taşır. Hiçbir satır yazılmamıştır. Bkz. Kurumsal Hesaplar.

Limit denominasyon uyuşmazlığı

WALLET_LIMIT_CURRENCY_MISMATCH — limit satırının tutar tavanları işlem para biriminden farklı bir para biriminde tanımlıdır. Kur çevirisi yapılmaz; tavan dürüstçe karşılaştırılamadığı için işlem reddedilir. Çözüm operatördedir: ilgili para birimi için bir limit satırı ekleyin. Bkz. Limitler.

Ürün yetkisi (PRODUCT_NOT_ENABLED)

Cüzdan API'si ürün kapılı bir yüzeydir: imzanız geçerli olsa bile, kimliğiniz cüzdan ürününe (WALLET_SERVICE) yetkili değilse hiçbir uç açılmaz — okuma uçları dahil.

PRODUCT_NOT_ENABLED alıyorsanız iki koşulun ikisi birden gerekir:

1. Organizasyonunuzun cüzdan ürününe aktif aboneliği olmalı
2. Çağrıda kullandığınız API anahtarının ürün listesinde WALLET_SERVICE yazmalı

Aboneliğiniz varken bu hatayı alıyorsanız neredeyse her zaman ikincisi eksiktir: API anahtarı bilinçli bir daraltmadır ve abonelik açıldığında mevcut anahtarlarınız kendiliğinden genişlemez. Ayrıntı: Hata Yönetimi.

Anahtar izni (WALLET_INSUFFICIENT_SCOPE)

Ürün yetkisinin yanında her cüzdan çağrısı, API anahtarında belirli bir izin ister — örneğin cüzdan içi para hareketi için wallet:operation:intervene, IBAN'a ya da banka hesabına para göndermek için wallet:bank-payout:operate. Denetim fail-closed çalışır: çağrı için gereken izni taşımayan anahtar reddedilir ve hiçbir işlem yürütülmez.

{
  "status": "failure",
  "code": "WALLET_INSUFFICIENT_SCOPE",
  "message": "…",
  "statusCode": 403,
  "requestId": "…"
}

Yaygın hatalar