Payven, tüm API’lerinde istek limitleri uygular. Limit organizasyonunuzun tamamına uygulanır: aynı organizasyon altındaki tüm API anahtarları, merchant’lar ve ürünlerin (Sanal POS, Para Transferi, Identity) toplam istek sayısı kotanızı belirler. Limit, suistimali engellemek ve adil kaynak paylaşımı sağlamak içindir.
Limitler
Limitler planınıza göre değişir. Tipik değerler:
| Plan | Saniyedeki istek (RPS) | Burst |
|---|
| Sandbox | 50 | 100 |
| Standart | 200 | 400 |
| Yüksek hacim | Anlaşmalı | Anlaşmalı |
Endpoint sınıfları ve özel limitler
Genel organizasyon limitinin yanında, bazı endpoint sınıflarında endpoint-bazlı ayrı limit uygulanır (suistimali önleme + kaynak adaleti):
| Endpoint sınıfı | Örnek path | Standart plan limiti | Not |
|---|
| Token endpoint | POST /auth/{slug}/token | 10 / dk / IP | Token cache’leyin; her istek için yeniden almayın |
| Refresh endpoint | POST /auth/{slug}/refresh | 30 / dk / organizasyon | — |
| Ödeme yazma | POST /payments, /refund, /void, /capture | Plan limiti dahilinde | Idempotency-Key ile retry edin |
| 3DS init | POST /payments/3d/init | Plan limiti dahilinde | callback_url redirect’ine kullanıcı yönlenirken kota tüketmez |
| Hosted Checkout oluşturma | POST /checkout/sessions | Plan limiti dahilinde | Müşteri sayfaya geçtikten sonra ek kota yok |
| Validasyon (BIN, IBAN, kart Luhn) | GET /lookups/bins/..., POST /validation/iban | 500 / dk | Cache’leyin — BIN verileri günde 1 kez güncellenir |
| Lookup servisleri | GET /lookups/banks, cities, mcc-codes | 1000 / dk | Long-cache (24h) tavsiye edilir |
Liste / arama (GET çoğul) | GET /transactions, /refunds, … | Plan limiti dahilinde | Cursor pagination kullanın (büyük veri) |
| Webhook subscription yönetimi | POST/PUT/DELETE /webhook-subscriptions | 20 / dk | Sık değişmemesi gereken; insan eli ile yönetilir |
| Mutabakat başlatma | POST /reconciliations/start | 5 / dk / organizasyon | EOD dosyaları nadir; yüksek hacim onboarding’de istenir |
| Toplu transfer | POST /transfers/bulk/create | 10 / dk / organizasyon | Tek pakette 1000’e kadar transfer; paketleri birleştirin |
| Health probe | GET /health/live, /ready | Limitsiz | Container orchestrator’ı için — kotaya yansımaz |
Webhook teslimleri rate limit’inden muaftır — Payven’in size gönderdiği webhook çağrıları sayılmaz; ayrı bir teslim mekanizmasına tabidir.
Yanıt başlıkları
Her API yanıtı, mevcut kotanızı bildiren başlıklar döner:
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1714742400
| Başlık | Açıklama |
|---|
X-RateLimit-Limit | Saniyedeki maksimum istek sayısı |
X-RateLimit-Remaining | Bu pencerede kalan istek hakkı |
X-RateLimit-Reset | Limitin sıfırlanacağı Unix timestamp |
Limit aşımı
Kotanız aşıldığında 429 Too Many Requests döner. Yanıt RFC 9457 problem+json formatındadır ve Retry-After header’ı kaç saniye bekleyeceğinizi belirtir:
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1
{
"type": "https://docs.payven.com.tr/errors/rate_limit_exceeded",
"title": "İstek limiti aşıldı",
"status": 429,
"code": "rate_limit_exceeded",
"detail": "İstek limiti aşıldı. Lütfen biraz sonra tekrar deneyin."
}
Önerilen istemci davranışı
async Task<HttpResponseMessage> SendWithBackoff(HttpRequestMessage request)
{
while (true)
{
var response = await http.SendAsync(request);
if (response.StatusCode != (HttpStatusCode)429) return response;
var retryAfter = response.Headers.RetryAfter?.Delta
?? TimeSpan.FromSeconds(1);
await Task.Delay(retryAfter);
}
}
Webhook teslimi rate limit’inden muaftır
Sizin endpoint’inize Payven’in gönderdiği webhook çağrıları bu limitlere dahil değildir — ayrı bir teslim mekanizmasına tabidir. Detay: Webhook Yeniden Deneme.
Limit artırma talebi
Yüksek hacim ihtiyacınız varsa destek ekibimize ulaşın. Tipik onboarding 1-2 iş günü sürer. 
