İstek Limitleri ve Planlar
API, ortak güvenlik ara katmanındaki hız sınırını ve kimliği doğrulanmış API anahtarının plan sınırını ayrı ayrı uygular. Aylık kullanım kotası üçüncü bir kontroldür. Bir katmanda kalan hakkın bulunması diğer katmanda erişim sağlamaz.
API Anahtarı Başına Hız Sınırı
Pencere 60 saniyedir; sayaç ilk istekte başlar. Aynı API anahtarının istekleri ortak sayılır; her endpoint için ayrı hak verilmez.
| Plan kodu | Etkin istek / 60 saniye |
|---|---|
PROFESSIONAL | 100 |
COMMERCIAL | 200 |
ENTERPRISE | 600 |
| Diğer plan kodları | 0; anahtar hız kontrolü erişimi 403 ile reddeder |
Etkin sınır, plan sınırı ile ortak global tavanın en küçüğüdür:
min(plan, 600). Enterprise plan sınırı 1.000 olsa da anahtar katmanı
etkin 600 sınırını uygular. Bu sınırlar ApiKeyAuthService tarafından
doğrulanmış anahtara uygulanır.
JWT ile yapılan çağrılar bu anahtar sayacına girmez; kendi yetki, kota ve ortak
ara katman kontrollerine tabidir.
Ortak Güvenlik Sınırı
Aşağıdaki değerler SecurityRateLimitMiddleware kurallarıdır. Sayaçlar sabit
saat dilimlerine değil, ilk istekten başlayan süre sonuna dayanır.
| Kapsam | İstek sınırı | Pencere |
|---|---|---|
mr_live_ anahtarı taşıyan /api/v1/changes, /api/v1/deadlines, /api/v1/actions, /api/v1/verification-reports, /api/v1/board-reports, /api/v1/evidence-packs ve alt yolları | 600 | 60 saniye |
Özel kurala girmeyen POST, PUT, PATCH, DELETE | 90 | 60 saniye |
| Özel kurala girmeyen diğer yöntemler | 2.400 | 60 saniye |
| Yapılandırılmış kimlik doğrulama yol önekleri | 120 | 60 saniye |
/api/v1/partners/click | 60 | 60 saniye |
/api/v1/partners/applications | 5 | 3.600 saniye |
/api/v1/referrals/click | 60 | 60 saniye |
/api/v1/referrals/validate | 120 | 60 saniye |
/api/v1/client-error öneki | 30 | 60 saniye |
Kimlik doğrulama önekleri /auth/login, /auth/register, /auth/magic,
/auth/trial, /auth/verify-email, /auth/change-password,
/api/v1/auth/saml ve /api/v1/partners/auth olarak tanımlıdır. Bu liste bütün
kimlik doğrulama endpointlerinin aynı limiti kullandığı anlamına gelmez;
endpoint üzerindeki ek kontroller ayrıca geçerlidir.
/health, /internal/server-telemetry, /api/v1/billing/webhooks ve
/api/v1/billing/callback önekleri bu ortak katmandan muaftır. Muafiyet
kimlik doğrulama veya endpoint üzerindeki diğer kontrolleri kaldırmaz.
Ortak katman kimlik bilgisi yoksa güvenilir istemci IP adresine göre sayar. API anahtarı veya JWT kimlik iddiası varsa kimlik kovasına ek olarak aynı IP üzerinde ilgili sınırın dört katı büyüklüğünde koruma kovası kullanır. Kimlik iddiası bu aşamada yetki kanıtı değildir. Kimlik doğrulama ve istemci hata katmanları yalnız IP üzerinden sayılır.
Örneğin Enterprise anahtarı /api/v1/changes için hem anahtar katmanında
hem ortak katmanda etkin 600 sınırına tabidir. Doğrulama raporları,
yönetim kurulu raporları ve kanıt paketleri de aynı anahtar kategorisindedir.
Bu altı kökte API anahtarı taşıyan istekler yöntemden bağımsız olarak bu
kategoriye girer. Diğer yollarda kimlik doğrulama, ortaklık, referans ve istemci
hata kuralları önceliklidir; özel kurala girmeyen mutasyonsuz anahtarlı istekler
600 sınırını, mutasyonlar 90 sınırını kullanır. JWT ile okuma sınırı 2.400 olarak
kalır. IP koruması ve endpoint özel kurallar nedeniyle pratik sınır daha düşük
olabilir. Sayaç hizmeti kullanılamazsa anahtarlı istek 503
RATE_LIMIT_UNAVAILABLE ve Retry-After: 5 alır; JWT okuma davranışı korunur.
Yanıt Başlıkları ve Hatalar
| Başlık | Anlamı |
|---|---|
X-RateLimit-Limit | Anahtar katmanında etkin sınır: min(plan, 600) |
X-RateLimit-Remaining | Anahtar katmanında etkin sınır eksi sayaç; en az 0 |
X-RateLimit-Reset | Pencerenin bitmesine kalan saniye; Unix zaman damgası değildir |
Retry-After | Reddedilen çağrı için bekleme süresi, saniye |
Anahtar katmanı çalıştığında ortak katmanın aynı adlı başlıklarını yeniden
yazar; X-RateLimit-Limit etkin sınırı gösterir (Enterprise: 600).
Başlıklar bütün katmanların kalan haklarının en küçüğünü göstermez.
Ortak IP koruması aşılmışsa başlıkta birincil kovanın sınırı görünmeye devam
edebilir; Retry-After reddeden kovanın kalan süresini taşır.
Ortak katmanın 429 yanıtı application/problem+json biçimindedir:
{
"type": "https://mevzuatradar.com/problems/rate_limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Çok fazla istek gönderdiniz. Lütfen kısa süre sonra tekrar deneyin.",
"instance": "/api/v1/changes",
"requestId": "req_example",
"errorId": "00000000-0000-4000-8000-000000000001",
"errorCode": "RATE_LIMITED",
"timestamp": "2026-10-24T12:00:00.000Z",
"success": false,
"error": "Çok fazla istek gönderdiniz. Lütfen kısa süre sonra tekrar deneyin.",
"statusCode": 429,
"path": "/api/v1/changes",
"retryAfterSeconds": 30
}Kimlikler, zaman ve bekleme süresi örnektir. Anahtar katmanının 429 mesajı
API key hız limiti aşıldı olur; aynı problem alanları hata filtresinden
gelir, ancak retryAfterSeconds alanı bu katmanın sözleşmesinde yoktur.
Redis kullanılamazsa ortak katman okuma kategorisini geçirir; diğer
kategoriler 503 ve Retry-After: 5 döndürür. Anahtar hız kontrolü de Redis
hatasında 503 ile erişimi reddeder. Üretimde ortak hız kontrolünün env ile
devre dışı bırakılması reddedilir.
Kullanım Kotaları
Aşağıdaki tablo başlangıç plan verileridir; canlı kurum kotası veya sözleşme taahhüdü değildir. Etkin abonelik, kurum limitleri ve ek haklar sonucu değiştirebilir.
| Plan | Genel API özelliği | Aylık çağrı | API anahtarı | Webhook endpointi |
|---|---|---|---|---|
| Starter | Kapalı | 0 | 0 | 0 |
| Professional | Açık | 1.000 | 2 | 3 |
| Commercial | Açık | 10.000 | 5 | 10 |
| Enterprise | Açık | 100.000 | 10 | Sabit sayısal taban sınırı yok (null) |
Kullanım değerleri apiCallsMonthly, apiKeysMax, webhookEndpointsMax
alanlarından çözülür. Çağrı kotası kurum düzeyindedir; yeni anahtar üretmek
aylık kotayı sıfırlamaz. Genel API okumasından sonra kullanım kaydı/kota
kontrolü yapılır; JWT çağrıları da kotaya dahildir. Webhook yönetimi ayrıca
webhooks özellik hakkını, ADMIN rolünü ve sayfa izinlerini gerektirir.
İstemci Bekleme Politikası
| Yanıt | Önerilen davranış |
|---|---|
429 | Önce Retry-After, ortak katmanda gerekirse retryAfterSeconds; yoksa sınırlı üstel bekleme ve rastgele gecikme |
500 / 503 | Salt okunur çağrılarda sınırlı yeniden deneme; varsa Retry-After dikkate alınır |
401 / 403 | Anahtar, izin, IP kısıtı ve plan kontrolü; aynı çağrı körlemesine tekrarlanmaz |
402 | Abonelik erişimi kontrol edilir |
Yazma çağrıları için otomatik yeniden deneme, işlem özelinde idempotency sözleşmesi doğrulanmadan uygulanmaz.
Entegrasyon uygulaması kovaları (kapalı beta)
mr_app_ çağrıları önce sırrın SHA-256 parmak iziyle global apikey tier’ına
girer; ham sır sayaç anahtarına yazılmaz. Kimliği doğrulanmış çağrı ayrıca
iki adet 60 saniyelik kovayı tüketir: uygulama + hedef kurum ve uygulama toplamı.
Sınır mevcut plan yardımcısından min(plan, 600) olarak hesaplanır. Bir kurumun
kovası diğer kurumun kovasını doldurmaz; toplam kova bütün kurumları sınırlar.
429 yanıtında Retry-After ve hız limiti başlıklarını izleyin. Redis hatasında
çağrı 503 ile kapatılır. Aylık kota dakikalık kovalardan ayrıdır ve ödeyen
kuruma bir kez yazılır: müşterinin kendi ücretli planı varsa müşteriye,
yoksa geçerli sponsorlu anlaşmada uygulamayı sunan firmanın ortak havuzuna.
Havuz bitince çağrı 429 INTEGRATION_QUOTA_EXHAUSTED alır; başka kurumun
sayacı artmaz. Kimlik ve hata ayrıntıları için
Uygulama ile istek bölümüne bakın.