Hata Kodları

Bu sayfa API uçlarının döndürdüğü hata kodlarını anlatır. Her kodun HTTP durumunu ve anlamını görürsünüz.

API hataları tek biçimli bir standart hata yanıtıyla döner. Bankanın ham hata kodları size yansıtılmaz. Yalnız bu sayfadaki kararlı kodları görürsünüz. Kararınızı code alanına göre verin. message insanlar içindir ve değişebilir.

Standart hata yanıtı

{
  "error": {
    "code": "terminal_not_allowed",
    "message": "Terminal is not allowed for this partner.",
    "traceId": "trc_9f12ab"
  }
}

Alan	Anlamı
code	Kararlı, makine tarafından okunan hata kodu. Değerler Kod kataloğu bölümündedir.
message	İnsan tarafından okunan açıklama. Değişebilir.
traceId	Destek talebinde paylaşacağınız izleme kimliği.

HTTP eşlemesi

• Doğrulama ve iş kuralı ihlalleri: 400, 409 ya da 422.
• API anahtarı doğrulaması başarısız: 401. Yetki ya da erişim reddi: 403.
• İstenen kayıt bulunamadı ya da hesabınıza ait değil: 404.
• Hız limiti aşıldı: 429. Yanıt, ne kadar bekleyeceğinizi bildiren bir Retry-After başlığı taşıyabilir.
• Platform geçici olarak kapasite tavanında: 503. Bu kod ayrılmıştır ve bugün üretilmez.
• Her hata yanıtı bir error.code ve traceId taşır.

Kod kataloğu

Genel

Kod	HTTP	Anlamı
validation_error	400	İstek gövdesi doğrulamadan geçmedi. Bir alan eksik ya da biçimi geçersiz.
unauthorized	401	İstekte Authorization başlığı yok. Ayrıntı: API Anahtarı ile Erişim.
invalid_token	401	Authorization başlığı var ama API anahtarı geçersiz, biçimi bozuk ya da iptal edilmiş. Ayrıntı: API Anahtarı ile Erişim.
partner_not_active	403	Hesabınız aktif değil. Hesap kapalıysa sorgular dahil her istek bu kodla reddedilir. Hesap askıdaysa yeni ödeme ve iade reddedilir, sorgular çalışır.
payment_acceptance_held	403	Hesabınız için ödeme alımı şu anda durdurulmuş. Yeni ödeme oluşturulmaz. Aynı istekle tekrar denemek sonucu değiştirmez. Daha önce oluşturulmuş ödemenin tamamlanması, sorgular ve iadeler etkilenmez. Nedenleri ödeme kabul durumu ucundan öğrenin.
rate_limited	429	Hız limiti aşıldı. Bir süre bekleyip tekrar deneyin.
service_overloaded	503	Platform geçici olarak kapasite tavanında. Ayrılmış koddur, bugün üretilmez. Aktif olduğunda yanıt Retry-After başlığı taşır. Bu süre kadar bekleyip artan aralıklarla tekrar deneyin. rate_limited ile karıştırmayın. O kod sizin kotanızın dolduğunu söyler. Bu kod platformun genel kapasite sinyalidir.

Ödeme oluşturma

Kod	HTTP	Anlamı
duplicate_partner_tx_code	409	Aynı partnerTxCode farklı bir istekle kullanımda. Aynı partnerTxCode ve aynı istek bu hatayı üretmez. 200 tekrar döner. Ayrıntı: Tekrar güvenliği.
terminal_not_allowed	403	Terminal hesabınıza ait değil ya da pasif.
amount_limit_exceeded	422	Hesabınıza tek işlem için bir alt ya da üst tutar sınırı tanımlıysa tutar bu aralığın dışında. Genel aralık her durumda geçerlidir. Negatif, 0 ya da 1.000.000.000 kuruşu aşan tutar 400 ve validation_error ile reddedilir.
installment_not_allowed	422	Kart taksite uygun değil, terminalin taksit izni yok ya da bu marka ve taksit sayısı terminalinizde sunulmuyor. Ayrıntı: Taksit uyumsuzluğu.
net_commission_basis_not_supported	422	Terminalinizin komisyon yapılandırması bu ödemeyi desteklemiyor. Bu bir kurulum sorunudur. Tekrar denemek sonucu değiştirmez. LydiaGate ile iletişime geçin.
pos_per_tx_limit_exceeded	422	Banka bağlantısına tanımlı işlem başı limit aşıldı. Ayrıntı: Banka bağlantısı limitleri.
pos_daily_limit_exceeded	422	Banka bağlantısına tanımlı günlük limit doldu.
pos_weekly_limit_exceeded	422	Banka bağlantısına tanımlı haftalık limit doldu.
pos_monthly_limit_exceeded	422	Banka bağlantısına tanımlı aylık limit doldu.
pos_time_window_limit_exceeded	422	Banka bağlantısına tanımlı, belirli bir saat aralığı için geçerli limit doldu.

Taksit sorguları

Kod	HTTP	Anlamı
validation_error	400	bin tam 8 hane değil, terminalId eksik ya da baseAmount 1’den küçük.
terminal_not_allowed	403	Terminal hesabınıza ait değil, pasif ya da kartın ailesi bu terminalde izinli değil.
commission_share_not_applicable	422	İstekte customerCommissionShareBps kısmi bir pay taşıyor. Belediye modelinde komisyonun tamamı kart sahibine yansır. Alanı göndermeyin ya da 10000 gönderin.

Sorgu

Kod	HTTP	Anlamı
payment_not_found	404	Ödeme bulunamadı ya da hesabınıza ait değil. partnerTxCode ile sorguda failed ya da expired ödemeler de bu kodu alır. Ayrıntı: Ödeme Sorgula.
refund_not_found	404	İade bulunamadı ya da hesabınıza ait değil.

İade ve iptal

Kod	HTTP	Anlamı
payment_not_refundable	422	Ödeme iade için uygun durumda değil.
refund_amount_exceeds_remaining	422	İstenen tutar kalan iade edilebilir tutarı aşıyor.
refund_not_yet_available	422	Varsayılan iade ucunda aynı işlem günü kısmi iade. Gün sonundan sonra yapılabilir.
refund_method_not_available	422	/refunds/void ucunda tutar kalan tutarın tamamına eşit değil ya da ödemede daha önce onaylanmış bir iade var.
refund_in_progress	409	Bu ödeme için pending bir iade var ya da bu partnerRefundCode daha önce kullanıldı.

Ayrıntı: İade ve İptal.

Taksit uyumsuzluğu

installment_not_allowed üç ayrı nedenden dönebilir:

1. Kart taksite uygun değil. Taksitli işlem yalnız belirli kartlarda desteklenir.
2. Terminalinize tanımlı taksit kümesi bu taksit sayısını kapsamıyor.
3. Kartın markası biliniyor ama bu marka ve taksit sayısı terminalinizde sunulmuyor.

Ne zaman döner: İkinci neden kartın markasına bağlı olmadığı için POST /v1/payments çağrısının kendisinde değerlendirilir. Birinci ve üçüncü nedenler kartın markasını gerektirdiği için yalnız Kart Handoff sırasında ortaya çıkar.

Kurtarma yolu: installment değeri ödeme oluşturulurken sabitlenir ve aynı ödemede değiştirilemez. Bu hatayı alırsanız farklı bir taksit sayısıyla yeni bir ödeme oluşturun. Aynı ödemede yalnız farklı bir kartla tekrar denenebilir. Birinci ve üçüncü nedenler 3D Secure sırasında ortaya çıktığı için her deneme ödemenin kart deneme hakkından düşer. Hak bitince ödeme failed olur ve paymentRef bir daha kullanılamaz. Bu hatayı önceden görmek için Taksit ve Toplam Tutar Sorgusu ucunu kullanın ve yalnız dönen listedeki taksit sayılarını sunun.

Banka bağlantısı limitleri

Terminalinizin bağlı olduğu banka bağlantısına banka tarafından işlem başı, günlük, haftalık, aylık ve belirli bir saat aralığı için ayrı limitler tanımlanmış olabilir. Bu limitlerden biri doluyken istek 422 ile reddedilir. Hangisinin dolduğunu dönen koddan anlarsınız. Eşik ve o anki kullanım değerleri hiçbir yanıtta yer almaz.

Kod	Pencere
pos_per_tx_limit_exceeded	İşlem başına
pos_daily_limit_exceeded	Günlük
pos_weekly_limit_exceeded	Haftalık
pos_monthly_limit_exceeded	Aylık
pos_time_window_limit_exceeded	Belirli bir saat aralığı

Ne zaman döner: iki ayrı anda karşınıza çıkabilir ve gösterim biçimleri farklıdır.

• Ödeme oluşturma anında: istek doğrudan sunucunuza 422 ile döner ve kod error.code alanındadır. Ödeme oluşturulmaz. partnerTxCode tüketilmez. Aynı istekle daha sonra tekrar deneyebilirsiniz.
• 3D Secure başlangıcında: ret kart sahibinin tarayıcısında gerçekleşir. Kart sahibi genel bir hata sayfası görür. Kod sunucunuza dönmez. Ödemenin durumu değişmez ve initiated kalır. Bu deneme kart deneme hakkından düşmez. Aynı paymentRef ile tekrar denenebilir.

Bu hatayı aldığınızda bir süre bekleyip tekrar deneyin ya da LydiaGate ile iletişime geçin.

Handoff hataları

Bu bölümdeki kodlar Kart Handoff sırasında oluşur. payment_ref_invalid, payment_ref_expired, payment_prepare_already_started ve card_attempt_limit_exceeded için çözüm aynıdır: yeni bir ödeme oluşturun ve dönen yeni paymentRef ile handoff’u baştan yapın. virtual_pos_inactive ve psp_inactive farklıdır. Banka bağlantısı geçici olarak pasiftir. Yeni ödeme oluşturmak aynı hatayı tekrar üretir. Durum düzelene kadar bekleyin ya da LydiaGate ile iletişime geçin. payment_declined karta bağlıdır ama yeni ödeme gerektirmez. Ödeme initiated kaldığı için kart sahibi aynı ödemede farklı bir kartla devam edebilir.

Kod	HTTP	Anlamı
payment_ref_invalid	404	paymentRef geçersiz ya da bilinmiyor.
payment_ref_expired	404	paymentRef süresi dolmuş.
payment_prepare_already_started	409	Bu paymentRef için 3D Secure zaten başlatılmış. Referans tek kullanımlıktır.
card_attempt_limit_exceeded	429	Bu paymentRef için izinli kart deneme sayısı aşıldı. Ödeme failed olur. Yeni bir ödeme oluşturun.
virtual_pos_inactive	422	Terminalin bağlı olduğu banka bağlantısı şu anda pasif. Yeni ödeme hazırlanamaz. Başlamış işlemler etkilenmez.
psp_inactive	422	Banka bağlantısının ödeme sağlayıcısı şu anda pasif. Yeni ödeme hazırlanamaz. Ödeme initiated kalır ve bu deneme kart deneme hakkından düşmez.
payment_declined	422	Banka kartı 3D Secure başlatılırken reddetti. Neden karta bağlıdır. Ödeme initiated kalır. Kart sahibi aynı ödemede farklı bir kart deneyebilir. Bu deneme kart deneme hakkından düşer. Hak bitince ödeme failed olur ve card_attempt_limit_exceeded döner.

Not

Bu sayfadaki kodlar size görünen kararlı kümedir. Bankanın ham kodları ve mesajları hata yanıtlarında yer almaz. Tek istisna iade sorgusudur. Orada yalnız sizin iadenize ait banka sonuç alanları döner. Ayrıntı: Bir iadenin durumunu sorgulama. Bir ödemenin sonucu yalnız status alanıyla ifade edilir.