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 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.
| HTTP | Anlamı |
|---|---|
| 400 | Body / 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). |
| 401 | Kimlik doğrulama / imza / IP / expiry hatası. |
| 403 | Anahtarı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ış. |
| 404 | Kayı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ı). |
| 409 | Idempotency ç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). |
| 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 | card/pay kaleminde name ya da pozitif unitPrice eksik, quantity pozitif değil veya vat negatif. |
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. |
amount.invalid | 400 | amount eksik, 0'dan büyük değil ya da 2'den fazla ondalık basamak içeriyor. |
refund.amount.exceeds.refundable.balance | 406 | İade toplamı, iade edilebilir kalan tutarı aşıyor. |
idempotency.key.required | 400 | Yazma ucunda Idempotency-Key header'ı gönderilmedi. |
idempotency.key.reused | 409 | Aynı Idempotency-Key farklı bir gövdeyle kullanıldı. |
idempotency.in.flight | 409 | Aynı Idempotency-Key ile ilk istek hâlâ işleniyor. |
partner.api.scope.missing | 403 | Anahtarınızda endpoint'in gerektirdiği scope yok. |
user.not.related | 403 | Kayıt (işlem, link) başka bir işletmeye ait. |
transactionRef.empty | 400 | transactionRef gönderilmedi (detay, kapama, iptal, iade). |
postransaction.not.found | 404 | transactionRef ile eşleşen işlem yok. |
pos.provider.not.found | 404 | İşletmenizde kart saklamaya uygun aktif bir POS sağlayıcısı yok. |
checkoutlink.not.found | 404 | Tahsilat linki bulunamadı. |
storedbankcard.not.found | 404 | Kayıtlı kart bulunamadı ya da size ait değil. |
checkoutrecurring.not.found | 404 | Tekrarlayan plan bulunamadı (başka işletmenin planında 403 ile döner). |
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:
{
"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.
Geçersiz imzalı istekler sayaca yazılmaz; yalnız public anahtarınızı bilen birinin kotanızı tüketmesi mümkün değildir.