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:

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

Scope yetersizse istek yine 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.

HTTP	Anlamı
400	Body / parametre validasyon hatası (ör. eksik zorunlu alan, tanımsız enum değeri, tutar > 0 değil) veya eksik `Idempotency-Key` header'ı.
401	Kimlik doğrulama / imza / IP / expiry hatası.
403	Anahtarınızda endpoint'in gerektirdiği scope yok.
404	Kayıt bulunamadı ya da işletmenize ait değil. Başka bir işletmenin kaydı da bu kodla döner — varlığı sızdıran ayrı bir kod yoktur.
406	İş kuralı ihlali (ör. geçersiz e-posta/telefon, geçmiş geçerlilik tarihi, sağlayıcı reddi, anahtar tavanının aşılması) veya idempotency çakışması — aynı anahtarın farklı gövdeyle kullanılması ya da ilk istek sürerken tekrar gönderilmesi.
429	Hız sınırı aşıldı (varsayılan 300 istek/dakika, anahtar bazında).
502 / 503 / 504	Sağlayıcı reddi, erişilemezliği ya da zaman aşımı. 503 ve 504 tekrar denenebilir.
5xx	Upstream / iç servis hatası.

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

Mesaj anahtarı	HTTP	Neden
`items.total.mismatch`	406	Sepet kalemlerinin toplamı gönderilen `amount` ile eşleşmiyor. Beklenen ve gönderilen tutar mesajda yer alır.
`items.limit.exceeded`	400	Tek istekte izin verilen kalem sayısı (250) aşıldı.
`items.invalid`	400	Kalemde `name`, `unitPrice` veya pozitif `quantity` eksik.
`pos.not.available`	406	İşletmenin POS'u kapalı.
`pos.non.secure.not.allowed`	406	Bu POS 3D'siz işleme kapalı — `threeDsEnabled: true` gönderin.
`transaction.amount.exceeds.per.transaction.limit`	406	Tutar, işletmenin işlem başına POS limitini aşıyor.
`pos.no.routing.rule.for.request`	406	İstenen para birimi/POS için tanımlı yönlendirme kuralı yok.
`checkout.not.captured`	406	Tahsil edilmemiş işlem iade edilemez.
`checkout.already.captured`	406	Tahsil edilmiş işlem iptal edilemez; iade kullanın.
`partner.api.amount.limit.exceeded`	406	Tutar, API anahtarınız için tanımlı üst sınırı aşıyor.
`partner.api.item.limit.exceeded`	406	Kalem sayısı, API anahtarınız için tanımlı üst sınırı aşıyor.
`pos.transaction.not.pre.authorized`	406	İşlem provizyon durumunda değil.
`pos.capture.exceeds.authorized`	406	Kapatma tutarı provizyon tutarını aşıyor.
`pos.reversal.rejected.by.provider`	406	Sağlayıcı iptal/iade isteğini reddetti; sağlayıcının ret gerekçesi mesajda yer alır.
`pos.commission.not.found`	406	İstenen yöntem + taksit için tanımlı komisyon yok — bu durumda ödeme de reddedilir.
`pos.amount.must.be.valid`	400	amount eksik ya da 0'dan büyük değil.
`invalid.payment.method`	400	Geçersiz `paymentMethod`. Boş bırakırsanız sunucu CARD / SAVED_CARD olarak türetir.
`paymenttransaction.not.found`	404	İşlem bulunamadı ya da işletmenize ait değil. Başka bir işletmenin işlemi de bu kodla döner.
`pos.provider.not.found`	404	İşletmenizde kart saklamaya uygun aktif bir POS sağlayıcısı yok.
`checkout.link.status.invalid`	406	Tahsilat linki bu işlem için uygun durumda değil.
`checkout.notfound`	400	Tahsilat linki bulunamadı ya da işletmenize ait değil.
`date.range.too.long`	400	Rapor 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:

HTTP/1.1 429
rate limit exceeded

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.