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 (yanıt bir Retry-After başlığı taşır; 429 ile karıştırılmamalıdır — bkz. aşağıdaki kod kataloğu).
• 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).
duplicate_partner_tx_code	409	Aynı partnerTxCode ile aktif/başarılı bir ödeme zaten var.
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	Tutar izin verilen min/maks aralığı dışında. Şu an uygulanmıyor (rezerve — tutar sınırı bugün yalnızca pozitiflik doğrulamasıdır; negatif ya da 0 tutar 400 validation_error ile reddedilir).
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	Aynı gün kısmi iade: gün sonu sonrasında yapılabilir.
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ş.
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. 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 API anahtarınıza özgü bir iş kuralıdır (siz izin verilenden fazla istek gönderdiniz); service_overloaded platformun genel kapasite sinyalidir — API anahtarınız ya da limitinizle bir ilgisi yoktur.

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).

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 farklıdır: terminalinizin bağlı olduğu banka bağlantı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.

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ı (virtual POS) şu anda pasif; yeni ödeme hazırlanamaz. Uçuştaki (zaten başlamış) işlemler bundan etkilenmez.
virtual_pos_card_type_not_supported	422	Terminalin bağlı olduğu banka bağlantısı (virtual POS) 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.

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.