Hata Kataloğu

Kimlik Doğrulama Hataları

/partner/1.0/... veri düzlemi, imza doğrulaması başarısız olduğunda HTTP 401 döner. Gövdedeki mesaj başarısızlık nedenini belirtir:

MesajNeden
missing api key, timestamp or signature headerX-Api-Key, X-Timestamp veya X-Signature header'ı eksik.
invalid timestampX-Timestamp sayı olarak ayrıştırılamadı.
stale timestampX-Timestamp sunucu saatinden ±5 dakika dışında.
invalid api keyAnahtar bilinmiyor veya aktif değil (revoked).
expired api keyAnahtarın geçerlilik süresi dolmuş.
ip not allowedİstek, anahtarın IP allowlist'i dışından geldi.
signature mismatchX-Signature beklenen imzayla eşleşmiyor.
replay detectedAynı imza 5 dakikalık pencere içinde ikinci kez görüldü.

Scope yetersizse istek partner.api.scope.missing mesajıyla 403 (errorCode 10009, errorGroup PERMISSION_DENIED) ile reddedilir; endpoint'in gerektirdiği scope entegrasyona verilmiş olmalıdır (bkz. Scope Kataloğu).

İş / Validasyon Hataları

İmza doğrulandıktan sonra istek gövdesi doğrulanır. Validasyon ve iş kuralı hataları aynı gövde yapısıyla döner:

{
  "code": 406,
  "message": "Sepet toplamı tutarla eşleşmiyor",
  "content": null,
  "correlationId": "3f6d1c2e-…",
  "errors": {
    "errorCode": "30008",
    "errorGroup": "BUSINESS_RULE",
    "errorDescription": "…",
    "userMessage": "…",
    "details": { },
    "traceId": "…",
    "retryable": false
  }
}

errors.errorCode makine tarafından ayırt edilecek koddur; retryable isteğin aynen tekrar denenebileceğini söyler. Kimlik doğrulama redlerinde (401/429) errors bulunmaz, neden message alanındadır.

HTTPAnlamı
400Body / parametre validasyon hatası (ör. eksik zorunlu alan, tutar > 0 değil, bozuk JSON) veya eksik Idempotency-Key header'ı. Tanımsız enum değerleri hata üretmez, boş kabul edilir (bkz. Genel Kurallar).
401Kimlik doğrulama / imza / IP / expiry hatası.
403Anahtarınızda endpoint'in gerektirdiği scope yok (partner.api.scope.missing), kayıt başka bir işletmeye ait (user.not.related, errorCode 30004) ya da gerekli modül işletmenizde satın alınmamış.
404Kayıt bulunamadı (ör. postransaction.not.found, checkoutlink.not.found, storedbankcard.not.found).
406İş kuralı ihlali (ör. geçersiz e-posta/telefon, geçmiş geçerlilik tarihi, sağlayıcı reddi, anahtar tavanının aşılması).
409Idempotency çakışması (errorCode 40002): aynı anahtarın farklı gövdeyle kullanılması (idempotency.key.reused) ya da ilk istek sürerken tekrar gönderilmesi (idempotency.in.flight).
429Hız sınırı aşıldı (varsayılan 300 istek/dakika, anahtar bazında).
502 / 503 / 504Sağlayıcı reddi, erişilemezliği ya da zaman aşımı. 503 ve 504 tekrar denenebilir.
5xxUpstream / iç servis hatası.

Sık Karşılaşılan İş Kuralı Mesajları

Mesaj anahtarıHTTPNeden
items.total.mismatch406Sepet kalemlerinin toplamı gönderilen amount ile eşleşmiyor. Beklenen ve gönderilen tutar mesajda yer alır.
items.limit.exceeded400Tek istekte izin verilen kalem sayısı (250) aşıldı.
items.invalid400card/pay kaleminde name ya da pozitif unitPrice eksik, quantity pozitif değil veya vat negatif.
pos.not.available406İşletmenin POS'u kapalı.
pos.non.secure.not.allowed406Bu POS 3D'siz işleme kapalı — threeDsEnabled: true gönderin.
transaction.amount.exceeds.per.transaction.limit406Tutar, işletmenin işlem başına POS limitini aşıyor.
pos.no.routing.rule.for.request406İstenen para birimi/POS için tanımlı yönlendirme kuralı yok.
checkout.not.captured406Tahsil edilmemiş işlem iade edilemez.
checkout.already.captured406Tahsil edilmiş işlem iptal edilemez; iade kullanın.
partner.api.amount.limit.exceeded406Tutar, API anahtarınız için tanımlı üst sınırı aşıyor.
partner.api.item.limit.exceeded406Kalem sayısı, API anahtarınız için tanımlı üst sınırı aşıyor.
pos.transaction.not.pre.authorized406İşlem provizyon durumunda değil.
pos.capture.exceeds.authorized406Kapatma tutarı provizyon tutarını aşıyor.
pos.reversal.rejected.by.provider406Sağlayıcı iptal/iade isteğini reddetti; sağlayıcının ret gerekçesi mesajda yer alır.
pos.commission.not.found406İstenen yöntem + taksit için tanımlı komisyon yok — bu durumda ödeme de reddedilir.
pos.amount.must.be.valid400amount eksik ya da 0'dan büyük değil.
amount.invalid400amount eksik, 0'dan büyük değil ya da 2'den fazla ondalık basamak içeriyor.
refund.amount.exceeds.refundable.balance406İade toplamı, iade edilebilir kalan tutarı aşıyor.
idempotency.key.required400Yazma ucunda Idempotency-Key header'ı gönderilmedi.
idempotency.key.reused409Aynı Idempotency-Key farklı bir gövdeyle kullanıldı.
idempotency.in.flight409Aynı Idempotency-Key ile ilk istek hâlâ işleniyor.
partner.api.scope.missing403Anahtarınızda endpoint'in gerektirdiği scope yok.
user.not.related403Kayıt (işlem, link) başka bir işletmeye ait.
transactionRef.empty400transactionRef gönderilmedi (detay, kapama, iptal, iade).
postransaction.not.found404transactionRef ile eşleşen işlem yok.
pos.provider.not.found404İşletmenizde kart saklamaya uygun aktif bir POS sağlayıcısı yok.
checkoutlink.not.found404Tahsilat linki bulunamadı.
storedbankcard.not.found404Kayıtlı kart bulunamadı ya da size ait değil.
checkoutrecurring.not.found404Tekrarlayan plan bulunamadı (başka işletmenin planında 403 ile döner).
date.range.too.long400Rapor aralığı 92 günü aşıyor.

Hız Sınırı

Her API anahtarı için dakikalık istek tavanı uygulanır (varsayılan 300 istek/dakika). Tavan aşılırsa istek HTTP 429 ile reddedilir:

{
  "code": 429,
  "message": "rate limit exceeded",
  "content": null,
  "correlationId": "3f6d1c2e-…"
}

Sayaç sabit pencerelidir (dakika başı sıfırlanır) ve anahtar bazında tutulur — birden fazla sunucudan istek atmanız sınırı değiştirmez. 429 alırsanız isteği bir süre bekletip tekrar deneyin; Idempotency-Key aynı kaldığı sürece tekrar denemek güvenlidir.

Sınır imza doğrulandıktan sonra işler

Geçersiz imzalı istekler sayaca yazılmaz; yalnız public anahtarınızı bilen birinin kotanızı tüketmesi mümkün değildir.