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 (müşteri, uç nokta) çifti için kayan 60 saniyelik bir sayaç tutulur: dakika, her biri 10 saniyelik altı alt-pencereye (kova) bölünür ve son altı kovanın toplamı değerlendirilir. Sayacı her istek 1 artırır — 429 ile reddedilenler dâhil. Son 60 saniyedeki toplam, tier'ın dakikalık limitini aştığında 429 dönmeye başlar.

• Tier'ın küresel sınırı her uç nokta için temel değerdir ve dakika başına istek sayısıdır.
• Uç nokta override'ı varsa küresel sınırın yerine onu kullanır. Örneğin tier sınırı dakikada 1000 ama semantik arama için dakikada 200 olabilir. /account/usage yanıtındaki byEndpoint listesi uç nokta başına aylık kotanızı gösterir (monthlyLimit, monthToDate, remaining); oran sınırı override'ları bu yanıtta yer almaz — yürürlükteki dakikalık sınırı her yanıttaki X-RateLimit-Limit başlığından okuyun.
• Sayaç saat başı ya da başka herhangi bir sabit anda sıfırlanmaz; pencere sürekli kayar — en eski 10 saniyelik kova düştükçe hakkınız kademeli olarak geri gelir. Bekleme süresi için her zaman Retry-After / X-RateLimit-Reset değerini kullanın; tipik olarak saniyeler mertebesindedir.

Yanıt başlıkları

Kimliği doğrulanmış her yanıt (başarılı veya 429) aşağıdaki başlıkları taşır:

Date: Tue, 14 Apr 2026 10:29:37 GMT
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 dakikalık hakkınız.
• X-RateLimit-Remaining — kayan pencerede şu an için kalan istek sayısı.
• X-RateLimit-Reset — ISO 8601 formatında (UTC) pencerenin bitiş anı. Unix timestamp değildir — ISO parser kullanın. Bu an saniyeler ötesindedir: başarılı yanıtlarda içinde bulunulan 60 saniyelik pencerenin bitişi (en fazla ~60 sn ileride), 429 yanıtlarında ise içinde bulunulan 10 saniyelik kovanın bitişi (en fazla ~10 sn ileride). Asla bir sonraki UTC saati değildir.

Oran sınırı durumu yalnızca bu başlıklarda döner; yanıt gövdesindeki meta nesnesinde taşınmaz.

Oran sınırı denetiminden ÖNCE reddedilen yanıtlarda bu başlıklar bulunmaz: 401 (eksik veya geçersiz anahtar), 403 + KEY_EXPIRED (süresi dolmuş anahtar) ve 403 + IP_NOT_ALLOWED (IP reddi) — aynı şekilde /health gibi muaf yollarda da. Buna karşılık 403 + FORBIDDEN (tier bu uç noktaya izin vermiyor) denetimden sonra üretilir: başlıkları taşır ve istek oran sayacınıza işlenir. İstemcinizde başlıkları okumadan önce varlıklarını kontrol edin.

Aylık kota

Dakikalık orandan bağımsız ikinci bir sınır vardır: tier'ınızda bir uç nokta için aylık istek kotası tanımlı olabilir. Kotası tanımlı uç noktalarda her yanıt şu başlıkları da taşır:

X-RateLimit-Month-Limit: 50000
X-RateLimit-Month-Remaining: 12480
X-RateLimit-Month-Reset: 2026-05-01T00:00:00.0000000Z

• Kota her ayın 1'i 00:00 UTC'de sıfırlanır; X-RateLimit-Month-Reset her zaman bir sonraki ay başını gösterir.
• Kota dolduğunda yanıt yine 429'dur, ancak gövdedeki kod RATE_LIMIT_EXCEEDED değil QUOTA_EXCEEDED'dır ve Retry-After ayın kalanı kadar — 31 güne varan — olabilir.
• Aylık kotası tanımlı olmayan (null) uç noktalarda bu üç başlık hiç gönderilmez. Kotası 0 veya negatif tanımlanmış bir uç nokta ise sınırsız sayılır, ancak başlıklar yine de gönderilir — bu durumda X-RateLimit-Month-Limit boş, X-RateLimit-Month-Remaining ise çok büyük bir sayı olur. Başlıkların varlığını kota olduğunun kanıtı saymayın.
• Aylık durumunuzu /account/usage yanıtındaki byEndpoint listesinden (monthlyLimit / monthToDate / remaining) izleyin.

429 yanıtı

429'un iki nedeni vardır; ayrımı yalnızca gövdedeki error.code yapar:

• RATE_LIMIT_EXCEEDED — dakikalık oran aşıldı. Hakkınız saniyeler içinde geri gelir; retry edilebilir.
• QUOTA_EXCEEDED — aylık kota doldu. Ay dönmeden retry anlamsızdır; plan yükseltmesi için [email protected].

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 7 seconds.",
    "retryAfter": 7
  },
  "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). Aylık kota 429'unu döngünün dışında bırakın; o sınır ay dönmeden temizlenmez:

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
        # Aylık kota ay dönene kadar açılmaz — retry etmeden çağırana dön.
        if r.json().get('error', {}).get('code') == 'QUOTA_EXCEEDED':
            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.