Hız Limitleri

Platform hız sınırlamayı iki katmanda uygular:

Katman	Nerede	Neyi korur
Kenar (firewall)	İstek API'ye ulaşmadan önce	Hacimsel kötüye kullanım, kaba kuvvet, dağıtık taşkın
Uygulama	Endpoint bazlı, kimlik doğrulandıktan sonra	Hassas işlemlerin kendine özgü eşikleri

Kenar katmanı taban korumadır ve kurulum bazında ayarlanır. Uygulama katmanı ise işlemin doğasına göre ayrı ayrı sınırlanır — aşağıda hepsi yazılı.

`429` yanıtı

Limit aşıldığında standart hata zarfı döner ve yanıt Retry-After başlığı taşır:

HTTP/1.1 429 Too Many Requests
Retry-After: 47

{
  "status": "failure",
  "code": "RATE_LIMITED",
  "statusCode": 429,
  "requestId": "req_7f3d9c1a4b2e"
}

⚠️

Retry-After saniyedir ve ona uyun. Kendi geri çekilme sürenizi uydurmayın — sunucu pencerenin ne zaman sıfırlanacağını biliyor, siz bilmiyorsunuz. Daha erken denemek yalnız sayacı besler.

Yüzeye göre üç kod dönebilir: RATE_LIMITED · RATE_LIMIT_EXCEEDED · ACTIVATION_RATE_LIMITED. Üçü de 429 taşır; ayrımı loglarken işinize yarar.

Endpoint bazlı limitler

Identity SDK

Pencere 60 saniye:

Uç	Limit
`analyze`	30 istek/dk
Tekil olay	120 istek/dk
Toplu olay (`events/batch`)	20 istek/dk
Uyumluluk kontrolü	60 istek/dk

Toplu ucunuz limiti düşüktür çünkü istek başına çok kayıt taşır. Yüksek hacimde tekil olay göndermek yerine toplu ucu kullanın — 20 toplu istek, 120 tekil istekten çok daha fazla olay taşır.

Cüzdan portalı

Kimlik doğrulama yüzeyi, kaba kuvvete karşı hem IP hem telefon bazında sınırlanır:

İşlem	IP başına	Telefon başına
Kayıt	3 / saat	3 / 5 dk
Giriş	10 / dk · 40 / saat	5 / dk
OTP doğrulama	10 / dk	—
OTP yeniden gönderim	5 / saat	—

İki eksenli olması kasıtlıdır. Yalnız IP'ye bakmak, IP değiştiren bir saldırganı durdurmaz; yalnız telefona bakmak, çok sayıda numara deneyen birini durdurmaz. İkisi birlikte her iki deseni de kapatır.

POS terminal aktivasyonu

Pencere 5 dakika:

Eksen	Limit
IP başına	10 deneme
Seri numarası başına	5 deneme

Seri numarası ekseni, geçerli bir terminalin kimliğini tahmin etmeye çalışan denemeleri sınırlar.

Banka hesapları — şimdi yenile

Pencere 60 saniye:

Uç	Limit
`POST /api/v1/bank-connect/accounts/{accountId}/sync`	API anahtarı başına 6 istek/dk

429 yanıtı RATE_LIMITED kodunu, Retry-After başlığını ve details.retryAfterSeconds alanını taşır. Okuma uçları bu limite sayılmaz. → Banka Hesapları › Sınırlar

Doğru yeniden deneme

async function callWithBackoff(fn: () => Promise<Response>) {
  for (let attempt = 0; attempt < 4; attempt++) {
    const res = await fn();
    if (res.status !== 429) return res;
 
    // Sunucunun söylediği süreye uyun; yoksa üstel geri çekilin
    const retryAfter = Number(res.headers.get('retry-after'));
    const waitSec = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter
      : 2 ** attempt;
 
    await new Promise(r => setTimeout(r, waitSec * 1000));
  }
  throw new Error('rate limit: deneme hakkı tükendi');
}

🚫

429'u sonsuz döngüde yeniden denemeyin. Bir üst sınır koyun ve sonra hatayı yukarı taşıyın. Sınırsız yeniden deneme, geçici bir yavaşlamayı kalıcı bir kesintiye çevirir — hem sizde hem bizde.

Limite takılmamak için

Toplu uçları kullanın. Olay beslerken events/batch, tekil çağrıdan kat kat verimlidir.
Token'ı önbelleğe alın. Her çağrıda token basmak gereksiz istek üretir. → Kimlik Doğrulama
Sayfalarken limiti büyütün. 100'lük sayfa, 25'lik sayfadan dört kat az istek demektir. → Sayfalama
Webhook'ları yoklayın, sorgulamayın. Durum değişikliğini öğrenmek için döngüyle sormak yerine webhook alın. → Webhook'lar

⚠️

Beklediğiniz hacim yukarıdaki limitlerin üstündeyse önceden haber verin — limite çarpıp keşfetmek yerine. İletişim: [email protected]

İlgili

Hata Yönetimi — zarf ve yeniden deneme kuralları
En İyi Uygulamalar — üretimde nelere dikkat edilir

Hata Yönetimi Webhook'lar