Hız Sınırlama

Her jekcms API uç noktası hız sınırlı. Sebep basit: kaçak bir script'in DB'yi boğup paylaşımlı hostingdeki diğer siteleri yavaşlatmasını istemiyoruz. Bu sayfa varsayılan üst sınırları, bir sınıra çarptığınızı nasıl anlarsınız, ne yaparsınız ve Enterprise lisansta nasıl yükseltirsinizi anlatıyor.

Varsayılan sınırlar

| Çağıran | Sınır | |--------|-------| | Token'lı (kimlik doğrulanmış) | 60 istek / dakika | | Token'sız | 10 istek / dakika | | Toplu uç noktalar | 5 istek / dakika |

"Toplu uç noktalar" tek istekte çok kayda dokunanlar — POST /posts/bulk, DELETE /comments/bulk, POST /media/bulk-import. Bunlar DB'de daha ağır iş yaptıkları için genel 60/dk bütçesinden ayrı, kendi sıkı sayaçları var.

Sayaç neye bağlı

Sayaç IP'ye değil, token'a bağlı. Aynı token'ı iki sunucu kullanıyorsa bütçeyi paylaşırlar. Ayrı bütçeler isterseniz ayrı token çıkarın — kaç token tutacağınıza sınır yok.

Pencere 60 saniyelik kayan pencere: her istek zaman damgalanır, oran "son 60 saniyedeki istek sayısı". Yani saat dakikasına bağlı sabit pencerelerin o can sıkıcı tarafı burada yok — 14:59:59'da 60 istek patlatıp 15:00:01'de bir 60 daha göndererek sistemi kandıramıyorsunuz (zaten kandırmaya çalışmayın).

Token'sız çağıranlar istemci IP'siyle izlenir. Kurumsal NAT veya ofisin tek dış IP'sinden çalışan herkes aynı 10/dk'yı paylaşır — pratikte sorun çıkarır. Çözüm: token kullanın.

429 yanıtı

Bütçeyi aşarsanız sonraki istek bunu alır:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1713710057

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit. Retry after 37 seconds.",
  "retry_after": 37
}

İşinize yarayacak header'lar:

Retry-After — tekrar bütçe kazanana kadar kaç saniye bekleyeceğiniz
X-RateLimit-Limit — etkin sınırınız (özel veya ENT katmanda değişebilir)
X-RateLimit-Remaining — bu pencerede kaç hak kaldı
X-RateLimit-Reset — sonraki tam yenilemenin Unix zaman damgası

Retry-After'a uyun, nokta. 429 aldığınızda sıkı bir döngüyle yeniden vurmak sınırı açmaz, tersine pencereyi sıfırdan başlatır ve durumu kötüleştirir.

Güzel haber: başarılı her istek de bu üç X-RateLimit-* header'ını taşır. Yani iyi davranan bir istemci Remaining 5'e düştüğünde kendi kendine yavaşlayabilir, 429'a hiç çarpmadan.

Nasıl yazılmalı

429 aldığınızda yapılacak en az şey bu:

import time, requests

def jekcms_request(method, url, **kwargs):
    for attempt in range(3):
        r = requests.request(method, url, **kwargs)
        if r.status_code != 429:
            return r
        wait = int(r.headers.get('Retry-After', 10))
        time.sleep(wait + 1)  # saat kayması için +1
    r.raise_for_status()
    return r

Çoğu HTTP kütüphanesinin hazır retry mekanizması var — Python'da urllib3.Retry, JavaScript'te axios-retry. Bunları sadece 429'da, Retry-After'a uyarak yeniden denemek üzere ayarlayın. Her hatada tekrar denemek dosya yüklemelerini ikiletmek gibi kötü sonuçlar doğurur.

Sınıra çarpmadan nasıl kalınır

Enterprise'a geçmeden önce aynı işi daha az çağrıyla yapıp yapamayacağınıza bakın. Çoğunlukla yapılabiliyor.

Toplu okuma

GET /posts?ids=1,2,3,...,100 tek istekte 100 yazı döndürür — bütçenizden 1 hak gider, 100 değil. Tüm liste uç noktaları ids= filtresini destekler.

İstemci tarafında cache

Kategori listesi, site ayarları, menü — bunlar nadiren değişir. Her sayfada /categories çekiyorsanız sonucu bir saat cache'leyin. Neredeyse hiç değişmeyen 20 satırlık bir listeyi her sayfa yükleyişinde çekmek API trafiğinizin %90'ını boş yere yiyor.

Her GET cevabı ETag ve Last-Modified header'ları taşır. Sonraki istekte If-None-Match veya If-Modified-Since gönderirseniz değişiklik yoksa 304 Not Modified alırsınız — bu cevap hız sınırınıza sayılmıyor. Bedava.

Yazmaları grupla

50 ayrı POST /comments/{id}/approve atmak yerine tek bir POST /comments/bulk ile { "ids": [...], "action": "approve" } yollayın. Bu, genel bütçeden 50 değil, toplu bütçesinden 1 slot tüketir.

Okuma ve yazmayı ayrı token'lara böl

"Salt okunur dashboard" için bir token, "admin yazma" için başka bir token. Her birinin kendi 60/dk bütçesi olur, yoğun bir raporlama cron'u editör araçlarınızı kesmez.

Enterprise'da yukarı ölçekleme

ENT lisansları sınırları kaldırır. Tipik yapılandırmalar:

| Çağıran | ENT varsayılanı | |--------|-------------| | Kimlik doğrulanmış | 600 istek / dk | | Toplu | 60 istek / dk | | IP başına anonim | 60 istek / dk |

Özel değerler sunucu tarafında config/config.php içinde RATE_LIMIT_* sabitleriyle ayarlanır. ENT müşterileri admin panelden bu düğmelere erişir; destek ekibi iş yükünüze göre mantıklı değerler önerir.

ENT olmayıp belirli bir uç noktanın (mesela yoğun webhook alıcısı) sınırsız olmasına ihtiyacınız varsa Settings → API → Rate-Limit Exemptions altında bir IP allow-list kurun. Listedeki IP'ler sayacı tamamen atlar.