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, kayan pencere (sliding window) yöntemiyle dakika / saat / gün olmak üzere üç pencerede eşzamanlı takip edilir. Bir istek, ancak her üç pencere de limitin altındaysa kabul edilir.

Rate limit, anlık burst/kötüye kullanım korumasıdır; aylık hacim ise Kredi Sistemi ile yönetilir. Günlük limit, planınızın aylık kredisine eşit tutulur — yani günlük limit hiçbir zaman kredinizden fazla istek yapmanıza izin vermez.

Plan Limitleri

Rate Limit Başlıkları

Her başarılı API yanıtı, dakikalık pencerenin durumunu bildiren başlıklar içerir:

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1752505260
X-RateLimit-Window: 60

429 Too Many Requests

Herhangi bir pencerede (dakika/saat/gün) limit aşıldığında API 429 döner. Mesaj, hangi pencerenin aşıldığını belirtir:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API istek limitinize ulaştınız. Dakikalık limit: 60 istek.",
    "details": {},
    "docsUrl": "https://docs.sosyalkopru.com/errors/rate-limit-exceeded"
  }
}

Yanıt yine yukarıdaki X-RateLimit-* başlıklarını taşır; X-RateLimit-Reset ile pencerenin ne zaman açılacağını öğrenebilirsiniz.

429’u Yönetme

Üretim kodunuzda 429 yanıtlarını X-RateLimit-Reset başlığına göre bekleyerek yönetin:

async function apiRequest(url: string, options: RequestInit, retries = 3): Promise<Response> {
  const res = await fetch(url, options);
 
  if (res.status === 429 && retries > 0) {
    const resetAt = parseInt(res.headers.get("X-RateLimit-Reset") ?? "0", 10) * 1000;
    const waitMs = Math.max(1000, resetAt - Date.now());
    console.warn(`Rate limit aşıldı. ${Math.ceil(waitMs / 1000)}s sonra yeniden deneniyor...`);
    await new Promise((r) => setTimeout(r, waitMs));
    return apiRequest(url, options, retries - 1);
  }
 
  return res;
}

Redis Kesintisinde Davranış

Rate limit servisi (Redis) geçici olarak erişilemezse:

• Okuma istekleri (GET, HEAD) açık kalır (fail-open) — bir Redis kesintisi genel API okuma erişimini düşürmemelidir.
• Yazma istekleri (POST, PATCH, DELETE) kapalı kalır (fail-closed) ve 503 SERVICE_UNAVAILABLE döner — kontrolsüz yazma trafiği (spam, retry fırtınası) rate limit’in engellemek için var olduğu asıl istismar vektörüdür.

Şüpheli Aktivite İzleme

Sistem, 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 eşik normal kullanımda aşılmaz; aşılıyorsa entegrasyonunuzu gözden geçirmeniz önerilir.