Temeller

Hız sınırı

İki katmanlı sınırlama, X-RateLimit başlıkları, 429 sonrası doğru davranış.

Hız sınırı iki katmanlıdır ve ikisi farklı şeyleri korur.

Katman 1 — IP ön-limiti

Anahtarın geçerliliği kontrol edilmeden önce çalışır: IP başına 10 saniyede 120 istek. Amacı, çöp blsk_ önekleriyle yapılan denemelerin veritabanına hiç ulaşmamasıdır.

Meşru bir entegrasyonun bu sınıra çarpması olağan değildir; çarpıyorsan muhtemelen paralelliği fazla açmışsındır.

Katman 2 — Anahtar başına limit

Doğrulama sonrası çalışır. Varsayılan dakikada 300 istek; anahtar bazında yükseltilebilir (destek talebiyle).

Her yanıt sınır durumunu söyler:

http
HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 41
BaşlıkAnlamı
X-RateLimit-LimitPencere başına izin
X-RateLimit-RemainingBu pencerede kalan
X-RateLimit-ResetPencerenin sıfırlanmasına kalan saniye

Sınıra çarptığında

json
{ "type": "error.list",
  "errors": [{ "code": "rate_limit_exceeded", "message": "Çok fazla istek." }] }

Yanıt 429 ve Retry-After başlığı taşır.

Retry-Afterı bekle. Sabit aralıklarla yeniden denemek pencereyi sürekli dolu tutar ve entegrasyonun hiç ilerlemez. Doğru davranış: Retry-After kadar bekle, sonra üstel geri çekilme (exponential backoff) ile devam et.

Örnek:

ts
async function istekAt(url: string, init: RequestInit, deneme = 0): Promise<Response> {
  const r = await fetch(url, init);
  if (r.status !== 429 || deneme >= 5) return r;

  const bekle = Number(r.headers.get("retry-after") ?? 1) * 1000;
  // Jitter ŞART: aynı anda sınıra çarpan 50 istemci aynı anda geri dönerse
  // sınır anında yeniden dolar ve hiçbiri ilerleyemez.
  const jitter = Math.random() * 250;
  await new Promise((c) => setTimeout(c, bekle + jitter + deneme * 500));
  return istekAt(url, init, deneme + 1);
}

Redis düşerse ne olur

Sınırlama altyapısı düştüğünde sistem tam serbest bırakmaz: süreç içi muhafazakâr bir pencereye (10 saniyede 30 istek) ve küresel bir eşzamanlılık tavanına düşer. Yani bir altyapı arızası, API'yi korumasız bırakmaz — ama normalden dar bir bantta çalışır. Bu dönemde 429 görme ihtimalin artar; aynı geri çekilme mantığı burada da doğru davranıştır.

Toplu iş yazarken

  • Paralelliği sınırla. 300/dk, saniyede 5 istek demektir; 50 paralel worker ilk saniyede sınırı yakar.
  • X-RateLimit-Remaininge bak. Kalan azaldıkça kendini yavaşlat; sınıra çarpıp geri dönmek, hiç çarpmamaktan pahalıdır.
  • Yazma işlerinde Idempotency-Key kullan. Geri çekilme sırasında yeniden gönderilen bir POST, anahtar olmadan ikinci kaydı doğurur.