Hız limitleri — plan başı üst sınırlar ve geri basınç

Hız sınırlaması (rate limiting) organizasyon başına ve API ağ geçidi (gateway) katmanında uygulanır. Üç boyut vardır:

1. Dakika başı istek (tüm uç noktaların toplamı)
2. Gün başı istek (24 saatlik kayan pencere)
3. Uç nokta başı özelleşme (üretim, refine, denetim — üst akıştaki LLM sağlayıcılarını korumak için ayrı bütçe)

Bu sayfayı bitirdiğinde

• Plan başına dakika / gün / eşzamanlı üst sınırları tablodan okuyabileceksin.
• Uç nokta başı özelleşmiş üst sınırları (üretim, refine, denetim) ayırt edebileceksin.
• Yanıt başlıklarından istemci tarafı geri basınç (backpressure) kurabileceksin.
• Hız limiti ile kota (quota) arasındaki farkı netleştireceksin.

Ön koşul: API anahtarı + bir uç nokta çağırmış olmak.

Plan başı varsayılan üst sınırlar

Üretim uç noktaları (POST /v1/personas, /refine, /fork) dakika başı üst sınırdan ayrı olarak eşzamanlı-üretim bütçesini yakar. Eşzamanlı 5 üretim çalışıyorsa 6. istek 429 rate_limited döner — dakikalık üst sınır dolmamış olsa bile.

Okumalar (GET *) eşzamanlı bütçeyi yakmaz; sadece dakika / gün üst sınırlarına sayılır.

Uç nokta başı özelleşmiş üst sınırlar

Bazı uç noktalar üst akıştaki LLM sağlayıcılarını korumak için dakika üst sınırından ayrı saatlik bütçe taşır:

Yanıt başlıkları

Her yanıt şunları taşır:

X-RateLimit-Limit:     3000        # dakika başı üst sınır
X-RateLimit-Remaining: 2987        # mevcut pencerede kalan
X-RateLimit-Reset:     1747498200  # pencere sıfırlama Unix zaman damgası

429 yanıtta ek olarak:

Retry-After: 12  # bir sonraki isteğin izinli olmasına kalan saniye

İstemci-tarafı geri basınç (backpressure) deseni

Üretimde 429'u bekleme; önce yavaşla. SDK'lar her çağrıdan sonra X-RateLimit-Remaining okur:

const client = new Moonborn({
  apiKey: process.env.MOONBORN_API_KEY,
  onRateLimitNearCap: ({ remaining, resetIn }) => {
    if (remaining < 50) {
      // Kuyruğu yavaşlat, operasyonu uyar, gecikmeli kuyruğa it
      setMyOwnBackpressure(resetIn);
    }
  },
});

Desen detayı:

1. remaining < cap × 0.1 → uyarı kaydet, kuyruk yavaşlatma etkin
2. remaining < cap × 0.05 → kritik uyarı, gerekli olmayan istekleri durdur
3. 429 alındığında → Retry-After kadar bekle, sonra yeniden dene
4. Sürekli 429 → plan yükselt veya toplu işleme dön (örn. POST /v1/personas/batch)

Hız limiti ile kota — karıştırma

İkisi de 429 döner ama farklı sebeplerle:

Örnek kota tetikleyicileri:

• Free planı: ayda 50 üretim aşıldı → quota_exceeded
• Pro planı: ayda 5.000 sohbet oturumu aşıldı → quota_exceeded

Aylık kotalar GET /v1/billing/usage ile izlenebilir; arayüz tarafında ilerleme çubuğu (progress bar) gösterebilirsin.

Enterprise — özel üst sınırlar

Sözleşme üzerinden organizasyon başına özel üst sınırlar. api.rate_limit.* yapılandırma maddeleriyle:

api.rate_limit.per_minute              (tamsayı, varsayılan plana göre)
api.rate_limit.per_day                 (tamsayı)
api.rate_limit.concurrent_generation   (tamsayı)
api.rate_limit.generation_per_hour     (tamsayı)
api.rate_limit.refine_per_hour         (tamsayı)
api.rate_limit.audit_per_hour          (tamsayı)

Owner rolüyle (Enterprise) bu yapılandırma maddeleri yazılabilir. Okuma için her plan.

Plan gereksinimi

Hız sınırlaması her plan'da etkindir. Plana göre üst sınırlar değişir; sistem her durumda korur.

Dürüst kapsam

İlgili