Rate Limiting

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ı

Aktif planınızı Konsol → Plan ve Kullanım ekranından görebilirsiniz.

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);
    }
}

async function sendWithBackoff(url, options) {
  while (true) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;
    const retry = parseInt(res.headers.get("Retry-After") ?? "1", 10);
    await new Promise((r) => setTimeout(r, retry * 1000));
  }
}

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.

Tanışın

Temel Kavramlar

Güvenlik

Geçiş Rehberi

Reçeteler

Limitler

Endpoint sınıfları ve özel limitler

Yanıt başlıkları

Limit aşımı

Önerilen istemci davranışı

Webhook teslimi rate limit’inden muaftır

Limit artırma talebi

​Limitler

​Endpoint sınıfları ve özel limitler

​Yanıt başlıkları

​Limit aşımı

​Önerilen istemci davranışı

​Webhook teslimi rate limit’inden muaftır

​Limit artırma talebi

Limitler

Endpoint sınıfları ve özel limitler

Yanıt başlıkları

Limit aşımı

Önerilen istemci davranışı

Webhook teslimi rate limit’inden muaftır

Limit artırma talebi