Hata Kodları

API hataları tutarlı bir standart hata yanıtı ile döner. Banka ham hata kodları (banka işlem/sonuç kodları) müşteri yüzeyine yansıtılmaz; yalnızca aşağıdaki kararlı kodları görürsünüz.

Standart hata yanıtı

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

Alan	Açıklama
code	Kararlı, makine-okunur hata kodu (aşağıdaki katalog).
message	İnsan-okunur açıklama.
traceId	Destek talebinde paylaşacağınız izleme kimliği.

HTTP statü eşlemesi

• Doğrulama ve iş kuralı ihlalleri → 4xx (örn. 400, 409, 422).
• Kimlik doğrulama başarısız → 401; yetki ya da erişim reddi → 403.
• İstenen kaynak bulunamadı ya da erişim kapsamınız dışında → 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 (rezerve — şu an üretilmez; ayrıntı ve 429 ayrımı için aşağıdaki kod kataloğuna bakın).
• Her hata yanıtı bir error.code ve traceId taşır.

Kod kataloğu

Kod	HTTP	Anlam
validation_error	400	İstek gövdesi doğrulamadan geçmedi (eksik ya da geçersiz alan).
sensitive_data_not_allowed	400	Bir serbest-metin alanı (örn. bir ödeme linkinin items[].name/items[].note/payerName alanı), boşluk ve - karakterleri çıkarıldıktan sonra alanın tamamı kart numarası ya da IBAN kalıbına uyan bir değer taşıyor. Kontrol yalnızca alanın tamamı bu kalıba uyduğunda tetiklenir; kart numarası ya da IBAN başka bir metnin içine gömülüyse istek reddedilmez.
duplicate_partner_tx_code	409	Aynı partnerTxCode farklı bir istekle kullanılmış (ya da bir ödeme linkine ait) — kod başka bir tahsilat için kullanımda. Aynı partnerTxCode + aynı istek bu hatayı üretmez; 200 idempotent tekrar döner. Bkz. Idempotency: partnerTxCode.
terminal_not_allowed	403	Terminal partnere ait değil ya da pasif.
partner_not_active	403	Partner hesabı aktif değil (askıda ya da kapalı); yeni ödeme ya da partner-başlatılan iade yapılamaz.
amount_limit_exceeded	422	Hesabınıza tek-işlem için bir min/maks tutar sınırı tanımlanmışsa, tutar bu aralığın dışında. Sınır tanımlı değilse (varsayılan) tutar kontrolü yalnızca pozitifliktir: negatif ya da 0 tutar 400 validation_error ile reddedilir.
pos_per_tx_limit_exceeded	422	Terminalinizin bağlı olduğu banka bağlantısına tanımlı işlem-başı bir limit aşıldı. amount_limit_exceeded’dan farklıdır: o hesabınıza tanımlı kendi sınırınızdır, bu banka bağlantınıza tanımlı bir sınırdır. Bkz. banka bağlantısı limitleri.
pos_daily_limit_exceeded	422	Terminalinizin bağlı olduğu banka bağlantısına tanımlı günlük limit doldu. Bkz. banka bağlantısı limitleri.
pos_weekly_limit_exceeded	422	Terminalinizin bağlı olduğu banka bağlantısına tanımlı haftalık limit doldu. Bkz. banka bağlantısı limitleri.
pos_monthly_limit_exceeded	422	Terminalinizin bağlı olduğu banka bağlantısına tanımlı aylık limit doldu. Bkz. banka bağlantısı limitleri.
pos_time_window_limit_exceeded	422	Terminalinizin bağlı olduğu banka bağlantısına tanımlı, belirli bir saat aralığı için geçerli bir limit doldu. Bkz. banka bağlantısı limitleri.
installment_not_allowed	422	Kart taksite uygun değil, terminalin taksit izni yok, kartın markası biliniyor ama bu marka × taksit sayısı terminalinizde sunulmuyor ya da bir ödeme linki’nin taksit kısıtı ihlal edildi. Bkz. taksit uyumsuzluğu altında kurtarma yolu.
payment_not_found	404	İstenen ödeme bulunamadı ya da bu partnere ait değil.
payment_not_refundable	422	Ödeme iade için uygun durumda değil.
refund_amount_exceeds_remaining	422	İstenen iade tutarı kalan iade edilebilir bakiyeyi aşıyor.
refund_not_yet_available	422	Otomatik iade ucunda (POST .../refunds) aynı işlem günü kısmi iade: gün sonu sonrasında yapılabilir.
refund_method_not_available	422	POST .../refunds/void ucunda zorlanan yöntem bu ödemede uygulanamaz: gönderilen tutar kalan bakiyenin tamamına eşit değil ya da ödemede daha önce onaylanmış bir Credit iadesi var.
refund_in_progress	409	Bu ödeme için bekleyen bir iade zaten var (tek uçuş) ya da bu partnerRefundCode daha önce kullanıldı (mükerrer kod).
refund_not_found	404	İstenen iade bulunamadı ya da bu partnere ait değil.
direct_refund_not_allowed	422	Bu işlem doğrudan-tahsilat (direct) bir terminalde yapıldı; Credit iadesi yapılamaz — yalnızca aynı gün içinde tam iptal (void) mümkündür.
payment_link_not_found	404	İstenen ödeme linki bulunamadı ya da bu partnere ait değil.
payment_link_already_paid	409	Ödeme linki zaten tamamlanmış. (Nadiren: iptal isteği tam o anda tamamlanan bir ödemeyle yarışırsa da aynı hata döner.)
payment_link_expired	409	Ödeme linkinin süresi dolmuş; artık iptal edilemez.
payment_link_cancelled	409	Ödeme linki zaten iptal edilmiş.
payment_link_items_amount_mismatch	422	Bir ödeme linki oluştururken gönderilen items kalemlerinin tutar toplamı amount alanına eşit değil. Kısmi kalem gönderimi desteklenmez.
rate_limited	429	Çok fazla istek: hız limiti aşıldı. Bir süre bekleyip tekrar deneyin.
service_overloaded	503	Platform o anda geçici olarak kapasite tavanındadır; isteğiniz kontrollü bir şekilde reddedildi. Şu an üretilmez (rezerve — kapasite kontrolü bugün gözlem modundadır; aktive edildiğinde bu davranış geçerli olur). Aktifken: yanıt bir Retry-After başlığı taşır (saniye cinsinden); bu süre kadar bekleyip üstel geri çekilme (exponential backoff) ile tekrar deneyin. ⚠ rate_limited (429) ile karıştırmayın: rate_limited, ilgili uç için API anahtarı, partner veya kaynak-IP eksenlerinden birindeki istemci kotasının aşıldığını belirtir; service_overloaded ise platformun genel kapasite sinyalidir.

Taksit uyumsuzluğu (installment_not_allowed)

installment_not_allowed dört ayrı nedenden dönebilir:

1. Kart takside uygun değil (taksitli işlem yalnızca belirli kartlarda desteklenir).
2. Terminalinizin efektif taksit kümesi (hesabınızda daraltılmış olabilir; bkz. Taksit Seçenekleri) bu taksit sayısını kapsamıyor.
3. Kartın markası biliniyor, ama bu marka × taksit sayısı terminalinizde sunulmuyor. Hangi taksit sayılarının sunulduğunu kesin olarak Taksit Seçenekleri ucundan öğrenirsiniz: listede olmayan her taksit sayısı bu hatayı üretir.
4. Bir ödeme linki oluştururken gönderdiğiniz allowedInstallmentCounts boştur ya da terminalinizin efektif taksit kümesinin alt kümesi değildir.

Ne zaman döner: 2. neden kartın markasına bağlı olmadığından POST /v1/payments çağrısının kendisinde (create anında) değerlendirilir. 1. ve 3. nedenler kartın markasını gerektirdiğinden yalnızca Kart Handoff’un 3D devri sırasında ortaya çıkar. 4. neden POST /v1/payment-links çağrısının create anında değerlendirilir.

Kurtarma yolu 1-3 nedenlerinde aynıdır: installment sayısı ödeme oluşturulurken (POST /v1/payments) sabitlenir ve aynı ödemede değiştirilemez. Bu hatayı alırsanız farklı bir taksit sayısıyla yeni bir kartsız ödeme oluşturun; aynı ödemeye yalnızca farklı bir kartla yeniden denenebilir, taksit sayısı sabit kalır. ⚠ Dikkat: 1. ve 3. nedenler 3D devri sırasında ortaya çıktığı için her deneme bu ödemenin kart-deneme hakkından düşer; hak bitince ödeme failed’a kilitlenir (card_attempt_limit_exceeded) ve paymentRef bir daha kullanılamaz. Yani “farklı kartla tekrar dene” yolu sınırsız değildir. Bkz. Ödeme Akışı — kart-deneme sınırı. Bu hatayı önceden görmek için checkout’unuzda Taksit Seçenekleri ucuyla kartın hangi taksitlere uygun olduğunu ve komisyon oranlarını önceden sorgulayın. 4. nedende kurtarma yolu, allowedInstallmentCounts listesini terminalinizin efektif taksit kümesinin bir alt kümesiyle yeniden göndermektir (link oluşturulduktan sonra bu kısıt değiştirilemez).

Banka bağlantısı limitleri

Terminalinizin bağlı olduğu banka bağlantısına bankanız tarafından işlem-başı, günlük, haftalık, aylık ve/ya belirli bir saat aralığı için ayrı limitler tanımlanmış olabilir. Bu limitlerden biri doluyken bir istek 422 ile reddedilir; hangisinin dolduğunu aşağıdaki beş koddan hangisinin döndüğünden anlarsınız. Eşik ya da 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: İki farklı anda karşınıza çıkabilir ve gösterim biçimleri farklıdır:

• Ödeme oluşturma anında (POST /v1/payments): İstek doğrudan sunucunuza 422 ile, ilgili kod error.code alanında döner. Ödeme oluşturulmaz; partnerTxCode tüketilmez, aynı istekle daha sonra tekrar deneyebilirsiniz.
• 3D başlangıcında (Kart Handoff sırasında): Ret alıcının tarayıcısında/WebView’inde gerçekleşir. Alıcı jenerik, steril bir hata sayfası görür — kod-özel bir mesaj gösterilmez ve error.code sunucunuza dönmez. Ödemenin durumu değişmez (initiated kalır) ve bu deneme kart-deneme hakkından düşmez; aynı paymentRef ile tekrar denenebilir. Bu davranış ödeme linki ile başlatılan ödemeler için de geçerlidir.

Bu hatayı aldığınızda bir süre bekleyip tekrar deneyin ya da işletmenizin yöneticisiyle iletişime geçin.

Handoff hataları

Aşağıdaki kodlar Kart Handoff sırasında oluşur. payment_ref_invalid / payment_ref_expired / payment_prepare_already_started / card_attempt_limit_exceeded için çözüm aynıdır: yeni bir kartsız ödeme (POST /v1/payments) oluşturun ve dönen yeni paymentRef/handoffUrl ile handoff’u baştan yapın. virtual_pos_inactive ve psp_inactive farklıdır: terminalinizin bağlı olduğu banka bağlantısı (ya da o bağlantının arkasındaki ödeme sağlayıcısı) geçici olarak pasif durumdadır; yeni bir ödeme oluşturmak aynı hatayı tekrar üretir — durum düzelene kadar bekleyin ya da destek ekibinizle iletişime geçin. virtual_pos_card_type_not_supported de farklıdır ve karta bağlıdır: aynı kartla yeni bir ödeme oluşturmak aynı hatayı tekrar üretir — alıcıdan başka bir kart isteyin. payment_declined da karta bağlıdır, ama yeni bir ödeme gerektirmez: ödeme initiated kaldığı için alıcı aynı ödemede farklı bir kartla devam edebilir.

Kod	HTTP	Anlam
payment_ref_invalid	404	paymentRef geçersiz/bilinmiyor.
payment_ref_expired	404	paymentRef’in süresi dolmuş.
payment_prepare_already_started	409	Bu paymentRef için 3D zaten başlatılmış (tek-kullanım).
card_attempt_limit_exceeded	429	Bu paymentRef’e izinli kart-deneme sayısı aşıldı; ödeme failed’a kilitlenir. Retry mantığınızda bunu farklı bir kartla tekrar deneme değil, yeni bir kartsız ödeme oluşturma tetikleyicisi olarak ele alın.
virtual_pos_inactive	422	Terminalin bağlı olduğu banka bağlantısı şu anda pasif; yeni ödeme hazırlanamaz. Uçuştaki (zaten başlamış) işlemler bundan etkilenmez.
psp_inactive	422	Terminalin bağlı olduğu banka bağlantısının ödeme sağlayıcısı şu anda pasif; yeni ödeme hazırlanamaz. Uçuştaki (zaten başlamış) işlemler bundan etkilenmez. Ödeme initiated kalır ve bu deneme kart-deneme hakkından düşmez.
virtual_pos_card_type_not_supported	422	Terminalin bağlı olduğu banka bağlantısı bu kart tipini desteklemiyor; ödeme hazırlanamaz. Pratikte bunu en çok yurt dışı ihraçlı kartlarda görürsünüz. Ödeme initiated kalır, ama bu deneme kart-deneme hakkından düşer. Önceden görmek için: Taksit Seçenekleri — desteklenmeyen bir kart tipinde options boş döner.
payment_declined	422	Banka, kartı 3D doğrulama başlatılırken reddetti (kart-düzeyi bir neden: örn. geçersiz kart, kapalı karta işlem). Ödemenin durumu değişmez (initiated kalır); alıcı aynı ödemede farklı bir kart deneyebilir. Bu deneme kart-deneme hakkından düşer; hak bitince ödeme failed’a kilitlenir (card_attempt_limit_exceeded).

Not

Yukarıdaki kodlar müşteri-görünür kararlı kümedir. Banka tarafından dönen ham kodlar/mesajlar API yanıtlarında yer almaz; bir ödemenin sonucu yalnızca status ile ifade edilir.