Oran Sınırları

Regvion API, kötü davranışlı bir müşterinin pahalı uç noktaları (semantik arama, AI analizi) tekelleştirmesini engellemek için isteklere oran sınırı uygular. Sınırlar tier bazlıdır; bazı uç noktalar için tier'dan daha sıkı özel sınır vardır.

Nasıl hesaplanır

Her (customerId, endpoint) çifti için saatlik bir Redis sayacı tutulur. Her başarılı istek sayacı 1 artırır; tier'ın saatlik limitine ulaşıldığında 429 dönmeye başlar.

• Tier'ın küresel sınırı her uç nokta için temel değerdir.
• Uç nokta override'ı (ApiTierPermission.EndpointRateLimit) varsa küresel sınırın yerine onu kullanır. Örneğin tier sınırı saatte 1000 ama semantik arama için override 200 olabilir.
• Sayaç saat başı sıfırlanır (UTC saatin 0. dakikasında).

Yanıt başlıkları

Her yanıt (başarılı veya 429) aşağıdaki başlıkları taşır:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2026-04-14T10:30:00.0000000Z

• X-RateLimit-Limit — bu uç nokta için saatlik hakkınız.
• X-RateLimit-Remaining — şu an için kalan istek sayısı.
• X-RateLimit-Reset — ISO 8601 formatında sayaç sıfırlanma anı (UTC). Unix timestamp değildir — ISO parser kullanın.

Aynı bilgi başarılı yanıtlarda meta.rateLimitRemaining / meta.rateLimitReset alanlarında da bulunur.

429 yanıtı

HTTP/1.1 429 Too Many Requests
Retry-After: 47
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 47 seconds.",
    "retryAfter": 47
  },
  "meta": { "requestId": "req_..." }
}

• Retry-After — standart HTTP başlığı, saniye cinsinden.
• error.retryAfter — aynı değer JSON gövdesinde, parse kolaylığı için.

Önerilen yeniden deneme stratejisi

Sabit aralık kullanmayın — birden çok client aynı anda geri dönüp tekrar 429 alır. Üstel geri çekilme + jitter (rastgelelik):

import time, random, requests

def call_with_backoff(method, url, headers, **kwargs):
    for attempt in range(5):
        r = requests.request(method, url, headers=headers, **kwargs)
        if r.status_code != 429:
            return r
        wait = int(r.headers.get('Retry-After', 2 ** attempt))
        jitter = random.uniform(0, wait * 0.25)
        time.sleep(wait + jitter)
    raise RuntimeError("Rate limit exceeded")

İyi uygulamalar

• Client tarafında limitleme — token bucket / leaky bucket algoritması ile istek akışını düzleştirin. Sunucuya ulaşmadan kendinizi sınırlayın; 429 üretmek maliyetlidir.
• Batch işler için kuyruk — gece çalışan senkronizasyon işleri için BullMQ, Sidekiq, SQS gibi bir kuyruk kullanın ve worker sayısını tier'ınıza göre ayarlayın.
• Önbelleğe hassas kullanım — aynı sorguyu 5 dakikada iki kez atmayın. Arama sonuçları sunucu tarafında 5 dk önbelleklenir; client tarafında da aynı sürede cache'leyin.
• /health limitsizdir — uptime monitoring istekleri oran sınırına sayılmaz.