> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limiting

> İstek limitleri, başlıklar ve aşım davranışı.

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](https://dashboard.payven.com.tr/my-plan) 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                 |

<Note>
  **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.
</Note>

## Yanıt başlıkları

Her API yanıtı, mevcut kotanızı bildiren başlıklar döner:

```http theme={null}
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 theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1
```

```json theme={null}
{
  "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ışı

<CodeGroup>
  ```csharp C# theme={null}
  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);
      }
  }
  ```

  ```javascript Node.js theme={null}
  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));
    }
  }
  ```
</CodeGroup>

## 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](/sanal-pos/webhooks/retry-policy).

## Limit artırma talebi

Yüksek hacim ihtiyacınız varsa [destek ekibimize](/resources/support) ulaşın. Tipik onboarding 1-2 iş günü sürer.