Rate Limiting

API, aşırı kullanımı önlemek ve tüm kullanıcılara adil hizmet sunmak için plan bazlı hız sınırlaması uygular. Limitler Redis üzerinde dakika / saat / gün pencerelerinde takip edilir.

Plan Limitleri

Plan	Dakika	Saat	Gün
STARTER	30 istek	500 istek	2.000 istek
GROWTH	100 istek	2.000 istek	20.000 istek
AGENCY_PRO	300 istek	10.000 istek	100.000 istek

Sandbox anahtarları (sk_test_) tüm limitlerin %10’u ile çalışır. Örneğin STARTER planı sandbox’ta dakikada 3 istek yapabilir.

Rate Limit Başlıkları

Her API yanıtı mevcut limit durumunu bildiren başlıklar içerir:


HTTP/1.1 200 OK
X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 27
X-RateLimit-Limit-Hour: 500
X-RateLimit-Remaining-Hour: 498
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1995

Başlık	Açıklama
`X-RateLimit-Limit-Minute`	Dakikadaki toplam limit
`X-RateLimit-Remaining-Minute`	Bu dakikadaki kalan hak
`X-RateLimit-Limit-Hour`	Saatlik toplam limit
`X-RateLimit-Remaining-Hour`	Bu saatteki kalan hak
`X-RateLimit-Limit-Day`	Günlük toplam limit
`X-RateLimit-Remaining-Day`	Bugünkü kalan hak
`Retry-After`	Yalnızca `429` yanıtında bulunur; kaç saniye beklenmesi gerektiğini belirtir

429 Too Many Requests

Herhangi bir pencerede limit aşıldığında API 429 döner:


{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Dakika limiti aşıldı. Lütfen 43 saniye bekleyin.",
    "details": {
      "window": "minute",
      "limit": 30,
      "retryAfter": 43
    }
  }
}

429’u Yönetme

Üretim kodunuzda 429 yanıtlarını exponential back-off ile yönetin:


async function apiRequest(url: string, options: RequestInit, retries = 3) {
  const res = await fetch(url, options);
 
  if (res.status === 429 && retries > 0) {
    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "5", 10);
    console.warn(`Rate limit aşıldı. ${retryAfter}s sonra yeniden deneniyor...`);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return apiRequest(url, options, retries - 1);
  }
 
  return res;
}

Şüpheli Aktivite İzleme

Sisteminiz, 5 dakika içinde 500+ istek yapan API anahtarlarını otomatik olarak şüpheli aktivite olarak işaretler ve hesap sahibine e-posta bildirimi gönderir. Bu limit normal kullanım durumlarında aşılmaz; aşılıyorsa entegrasyonunuzu gözden geçirmeniz önerilir.

Rate limitler API anahtarı bazında takip edilir; aynı hesaba ait birden fazla anahtarın limitleri birbirinden bağımsızdır.