Hata Kodları
Hatalar ortak hata zarfıyla döner. Dallanmayı message'a göre değil, code'a göre yapın; zarfın alanları ve genel kurallar: Hata Yönetimi.
{
"status": "failure",
"code": "bank_connect.validation.invalid",
"message": "Banka bağlantısı isteği geçersiz — ayrıntılar `details.errors` alanında.",
"statusCode": 400,
"requestId": "00000000-0000-0000-0000-000000000000",
"details": {
"errors": [{ "field": "bookedTo", "reason": "range_too_large" }]
}
}Özet
Para transferi ve döviz işleminde banka tarafında oluşan sonuçlar HTTP hatası olarak değil, kaydın failureCode alanında döner: Transfer sonuç kodları · Döviz sonuç kodları.
Kod sözlüğü
bank_connect.validation.invalid
İstek bu ürünün bir kuralına uymuyor. Sebep details.errors[] içindedir: her öğe field (alan) ve reason (sebep) taşır. Hareket listesinde sık görülen sebepler:
reason | Sebep |
|---|---|
booked_from_required | bookedTo var, bookedFrom yok. |
after_booked_to | bookedFrom, bookedTo'dan sonra. |
range_too_large | Tarih aralığı 92 günden uzun. |
min_greater_than_max | minAmountMinor, maxAmountMinor'dan büyük. |
invalid | Değer okunamadı. |
Para transferi ve döviz isteklerinde field alan adını alt çizgiyle verir (receiver_iban, amount_minor …):
field | reason | Sebep |
|---|---|---|
receiver_iban | required, invalid | IBAN yok ya da TR IBAN kontrol hanesi tutmuyor. |
receiver_name | required, length, invalid_characters | Alıcı adı yok, 2–140 karakter dışında ya da izin verilmeyen karakter içeriyor. |
amount_minor | must_be_positive_integer | Tutar sıfırdan büyük bir tam sayı değil. |
currency | invalid | Para birimi üç harfli ISO 4217 kodu değil. |
payment_purpose | invalid | Ödeme amacı kodu biçim dışı. |
description | too_long, invalid_characters | Açıklama 140 karakterden uzun ya da izin verilmeyen karakter içeriyor. |
target_account_id | same_as_source | Döviz teklifinde kaynak ve hedef hesap aynı. |
amount | exactly_one_of_source_or_target | Döviz teklifinde iki tutar birden ya da hiç tutar gönderilmedi. |
İsteği düzeltip yeniden gönderin. → Hareketler › Tarih aralığı kuralları
bank_connect.cursor.invalid
Sayfalama imleci tanınmadı. İmleci kendiniz üretmeyin ya da değiştirmeyin; bir önceki yanıttaki pageInfo.nextCursor değerini aynen gönderin. Süzgeçleri değiştirdiyseniz imleci sıfırlayıp ilk sayfadan başlayın. → API'ye Giriş › Sayfalama
bank_connect.connection.not_found
Bağlantı bulunamadı. Kimlik yanlış, biçimi geçersiz, kayıt başka bir organizasyona ait ya da anahtarınızın ortamında değil. Test anahtarı canlı bağlantıları, canlı anahtar test bağlantılarını görmez.
bank_connect.account.not_found
Hesap bulunamadı. Kimliği ve anahtarınızın ortamını kontrol edin. Hesap kimliklerini Hesaplar ucundan alın.
bank_connect.transaction.not_found
Hareket bulunamadı. Kimliği ve anahtarınızın ortamını kontrol edin. Hareket kimliklerini Hareketler ucundan ya da webhook'taki data.transactionId alanından alın.
bank_connect.connection.not_active
Şimdi Yenile isteği, hesabın bağlantısı okunabilir durumda olmadığı için kabul edilmedi. Yenileme yalnız ACTIVE ve DEGRADED bağlantılarda yapılır. Bağlantının durumunu Bağlantılar ucundan kontrol edin; durumun anlamı ve ne yapmanız gerektiği: Kavramlar › Bağlantı durumları.
bank_connect.internal.integrity
İstek sunucu tarafında tamamlanamadı; isteğinizde düzeltilecek bir şey yoktur. Üstel geri çekilmeyle yeniden deneyin. Sorun sürerse yanıttaki requestId değeriyle destek ekibine başvurun.
Para hareketi — IP izin listesi kodları
bank_connect.auth.ip_allowlist_required
Para hareketi uçları (bank-connect:transfer) IP izin listesi tanımlı bir API anahtarı ister; anahtarınızın listesi boş. Panelde anahtara sunucunuzun çıkış IP adreslerini ekleyin. → API'ye Giriş › IP izin listesi
bank_connect.auth.ip_not_allowed
İsteğin geldiği IP adresi anahtarın izin listesinde değil. Sunucunuzun çıkış adresi değiştiyse (yeni sunucu, NAT, yük dengeleyici) listeyi güncelleyin. Değişiklik en geç 15 saniye içinde geçerli olur.
bank_connect.auth.ip_allowlist_unavailable
IP izin listesi şu anda doğrulanamadı; istek güvenlik için reddedildi. İsteğinizde düzeltilecek bir şey yoktur; aynı istekle (aynı Idempotency-Key ile) geri çekilerek yeniden deneyin.
Para transferi kodları
bank_connect.transfer.not_found
Transfer bulunamadı. Kimlik yanlış, biçimi geçersiz, kayıt başka bir organizasyona ait ya da anahtarınızın ortamında değil.
bank_connect.transfer.capability_unavailable
Bu bağlantıda para transferi kullanılamıyor. Bağlantının capabilities alanında OUTGOING_TRANSFER olmalıdır. → Bağlantılar
bank_connect.transfer.account_not_eligible
Bu hesaptan şu anda transfer ya da döviz işlemi yapılamıyor. details.reason sebebi verir: account_inactive (hesap etkin değil), connection_not_active (bağlantı ACTIVE ya da DEGRADED değil), credential_not_active (bankanızın verdiği bilgiler geçersiz; panelde güncelleyin).
bank_connect.transfer.invalid_state
Transfer bu işlem için uygun durumda değil (ör. onay bekleyen bir transfer zaten onaylandı ya da iptal edildi). Transferin güncel durumunu sorgulayın.
bank_connect.transfer.idempotency_conflict
Bu Idempotency-Key daha önce farklı bir gövdeyle kullanıldı. Aynı transferi yeniden gönderiyorsanız gövdeyi birebir aynı tutun; yeni bir transfer için yeni anahtar kullanın.
bank_connect.transfer.idempotency_key_required
Transfer ve döviz işlemi oluşturmada Idempotency-Key başlığı zorunludur. → Para Transferi › Idempotency-Key
bank_connect.transfer.idempotency_key_invalid
Idempotency-Key 8–200 yazdırılabilir ASCII karakter olmalıdır; boşluk ve Türkçe karakter içermez.
bank_connect.transfer.currency_unsupported
Bu para biriminde transfer desteklenmiyor. Bugün yalnız TRY transfer yapılabilir; currency alanını TRY gönderin ya da boş bırakın.
Döviz işlemi kodları
bank_connect.fx.quote_not_found
Döviz teklifi bulunamadı. Teklif kimliğini ve anahtarınızın ortamını kontrol edin.
bank_connect.fx.quote_expired
Teklifin süresi doldu. Yeni teklif alıp süresi dolmadan işlem açın. İşlem açıldıktan sonra bankaya iletilmeden süre dolarsa işlem FAILED olur ve bu kod failureCode alanında döner.
bank_connect.fx.quote_used
Bu teklifle zaten bir işlem açıldı; bir teklif yalnız bir işlemde kullanılır. Aynı işlemi yeniden gönderiyorsanız aynı Idempotency-Key ile gönderin.
bank_connect.fx.order_not_found
Döviz işlemi bulunamadı. Kimliği ve anahtarınızın ortamını kontrol edin.
bank_connect.fx.pair_unsupported
Banka bu iki para birimi arasında işlem yapmıyor.
bank_connect.fx.accounts_invalid
Hesaplar döviz işlemi için uygun değil: kaynak ve hedef hesap aynı bağlantıda, farklı para biriminde ve etkin olmalıdır. Sebep details.reason alanındadır.
bank_connect.fx.capability_unavailable
Bu bağlantıda döviz işlemi kullanılamıyor. Bağlantının capabilities alanında FX_EXCHANGE olmalıdır.
bank_connect.fx.invalid_state
Döviz işlemi bu işlem için uygun durumda değil. İşlemin güncel durumunu sorgulayın.
bank_connect.fx.idempotency_conflict
Bu Idempotency-Key daha önce farklı bir gövdeyle kullanıldı. Yeni bir işlem için yeni anahtar kullanın.
bank_connect.fx.quote_rejected
Banka teklif vermedi. Sebep details.reasonCode alanında bir döviz sonuç kodudur (ör. bank_connect.fx.market_closed, bank_connect.fx.below_minimum, bank_connect.fx.limit_exceeded). Sebebe göre tutarı değiştirin ya da daha sonra deneyin.
Panel doğrulama kodları
Aşağıdaki kodlar yalnız panelden yapılan transfer ve döviz işlemlerinde, e-posta doğrulama adımında görülür. API anahtarıyla yapılan isteklerde doğrulama kodu yoktur.
bank_connect.transfer.actor_mismatch
Panelde transferi ya da döviz oturumunu yalnız başlatan kullanıcı onaylayabilir.
bank_connect.transfer.otp_invalid
E-posta doğrulama kodu hatalı.
bank_connect.transfer.otp_expired
Doğrulama kodunun ya da onay süresinin süresi doldu; yeni kod isteyin. Süresinde onaylanmayan panel transferi iptal edilir ve failureCode alanında bu kod görünür.
bank_connect.transfer.otp_resend_limited
Yeni kod için biraz bekleyin: kodlar en az 30 saniye arayla ve işlem başına en çok 5 kez gönderilir.
bank_connect.transfer.step_up_unavailable
Doğrulama kodu şu anda gönderilemiyor; biraz sonra yeniden deneyin.
bank_connect.transfer.step_up_actor_required
Bu işlem panel kullanıcısıyla yapılır; panel oturumunuzu yenileyip yeniden deneyin.
bank_connect.fx.session_required
Panelde döviz teklifi ve işlemi için önce e-posta doğrulama kodunu onaylayıp döviz oturumu açmanız gerekir.
bank_connect.fx.session_not_found
Döviz oturumu bulunamadı; yeniden Döviz çevir ile başlayın.
bank_connect.fx.session_expired
Döviz oturumunun 5 dakikalık süresi doldu; süre uzatılmaz. Yeni kod isteyip yeni oturum açın.
bank_connect.fx.session_invalid_state
Döviz oturumu bu işlem için uygun durumda değil (ör. kod henüz onaylanmadı ya da zaten onaylandı).
bank_connect.fx.session_scope_mismatch
Döviz oturumu başka bir banka bağlantısı için açıldı; bu bağlantı için yeni oturum açın.
Transfer sonuç kodları
Bu kodlar HTTP hatası olarak dönmez; FAILED, RETURNED ya da CANCELED transferin failureCode alanında ve bank_transfer.failed / bank_transfer.returned webhook'unda görülür. Transferi oluşturan istek 201 döner; sonuç sonradan gelir.
bank_connect.transfer.insufficient_balance
Hesap bakiyesi yetersiz.
bank_connect.transfer.limit_exceeded
Bankadaki transfer limiti aşıldı ya da tanımlı değil. Limitinizi bankanızla kontrol edin.
bank_connect.transfer.eft_cutoff_passed
EFT kapanış saati geçti; transferi bir sonraki iş gününde yeniden gönderin.
bank_connect.transfer.invalid_amount
Banka tutarı geçersiz buldu.
bank_connect.transfer.invalid_request
Banka transfer isteğini geçersiz buldu.
bank_connect.transfer.invalid_payment_purpose
Ödeme amacı geçersiz; ödeme amaçları ucundan bir kod seçin.
bank_connect.transfer.receiver_name_mismatch
Alıcı adı IBAN sahibiyle eşleşmedi. Adı IBAN sahibinin adı ya da unvanıyla aynı yazın.
bank_connect.transfer.receiver_bank_not_supported
Alıcı bankası bu transfer türünü desteklemiyor.
bank_connect.transfer.rejected_by_bank
Banka transferi reddetti; ayrıntı için bankanızla görüşün.
bank_connect.transfer.canceled_by_user
Transfer panelden iptal edildi.
bank_connect.transfer.canceled_by_bank
Transfer banka tarafından iptal edildi.
bank_connect.transfer.returned_by_bank
Tamamlanan transfer alıcı bankadan iade edildi; transfer RETURNED olur.
bank_connect.transfer.outcome_unknown
Transferin sonucu bankadan teyit edilemedi; Lunixi sonucu bankayla doğruluyor. Transferi yeniden göndermeyin.
bank_connect.transfer.failed_after_bank_check
Sonuç bankada kontrol edildi: transfer gerçekleşmedi. Ödemeyi yeni bir Idempotency-Key ile yeniden gönderebilirsiniz.
Döviz sonuç kodları
Bu kodlar FAILED döviz işleminin failureCode alanında ve teklif reddinde bank_connect.fx.quote_rejected hatasının details.reasonCode alanında görülür.
bank_connect.fx.insufficient_balance
Kaynak hesabın bakiyesi yetersiz.
bank_connect.fx.below_minimum
Tutar bankanın alt sınırının altında.
bank_connect.fx.limit_exceeded
Bankadaki günlük ya da aylık döviz işlem limiti aşıldı.
bank_connect.fx.market_closed
Döviz piyasası şu anda kapalı (ör. hafta sonu); piyasa açıkken yeniden deneyin.
bank_connect.fx.invalid_request
Banka döviz isteğini geçersiz buldu.
bank_connect.fx.rejected_by_bank
Banka döviz işlemini reddetti.
bank_connect.fx.outcome_unknown
İşlemin sonucu bankadan teyit edilemedi; Lunixi sonucu bankayla doğruluyor. İşlemi yeniden açmayın.
bank_connect.fx.failed_after_bank_check
Sonuç bankada kontrol edildi: döviz işlemi gerçekleşmedi. Yeni teklif alıp yeni işlem açabilirsiniz.
Ortak kodlar
Bu uçlarda aşağıdaki platform kodları da dönebilir. Anlamları ve çözümleri ortak sayfalardadır:
code | HTTP | Nerede |
|---|---|---|
VALIDATION_ERROR | 400 | Tanımlanmamış parametre, geçersiz süzgeç değeri, limit 1–100 dışında. → Hata Yönetimi |
AUTH_HEADERS_MISSING, INVALID_SIGNATURE, NONCE_REPLAY, INVALID_DATE | 401 | İmza başlıkları eksik ya da imza doğrulanamadı. → Hata Yönetimi |
PRODUCT_NOT_ENABLED | 403 | Anahtarda Banka Bağlantıları ürünü yok. → Hata Yönetimi |
API_INSUFFICIENT_SCOPE | 403 | Anahtarda ucun yetkisi yok (para hareketi uçlarında bank-connect:transfer). → API'ye Giriş › Yetkiler |
RATE_LIMITED | 429 | Şimdi yenile ya da para hareketi istek limiti aşıldı. → Sınırlar |
Bu sayfadaki kodlar zamanla artabilir. Tanımadığınız bir bank_connect.* kodunu HTTP durumuna göre ele alın: 4xx isteği değiştirmeden yeniden denemeyin, 5xx geri çekilerek yeniden deneyin.