Hız sınırları ve kota
Plan bazlı API istek hızı (api_rps), X-RateLimit başlıkları, 429 ve Retry-After davranışı, uç başına özel sınırlar, nginx IP sınırları, plan kotaları ve SDK yeniden deneme kuralları.
Pushizo iki katmanda sınır uygular: uygulama içi token kovası (API anahtarı/aktör başına, Redis) ve kenar katmanında IP bazlı nginx sınırı. Plan kotaları (abone, aylık mesaj, app, üye) ayrı bir mekanizmadır.
Plan bazlı istek hızı
API anahtarıyla yapılan isteklerde kova kapasitesi planın api_rps değeridir (saniyede dolar):
| Plan | api_rps | Abone | Mesaj / ay | App | Üye | Saklama |
|---|---|---|---|---|---|---|
| Free | 20 | 10.000 | 100.000 | 1 | 3 | 30 gün |
| Starter | 100 | 50.000 | 1.000.000 | 3 | 10 | 90 gün |
| Growth | 500 | 500.000 | 10.000.000 | 10 | 50 | 365 gün |
| Enterprise | 2.000 | sınırsız | sınırsız | sınırsız | sınırsız | 730 gün |
Değerler plan matrisinden okunur (planlar ve kota); kendi kurulumunuzda plan tanımları değiştirilebilir. Bazı uçlar kendi daha dar sınırını taşır (ör. kişisel veri indirme 5 istek / 5 dk, SDK hata raporları, kayıt/giriş).
Yanıt başlıkları
Her yanıt şu başlıkları taşır:
| Başlık | Anlam |
|---|---|
X-RateLimit-Limit | Kova kapasitesi (izin verilen ani istek sayısı) |
X-RateLimit-Remaining | Kovada kalan hak |
X-RateLimit-Reset | Kova tamamen dolana (429 ise yeniden denenebilene) kadar saniye |
Aşımda:
HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2
{ "error": { "code": "HS_RATE_LIMITED", "message": "…", "details": { "retry_after_seconds": 2 }, "request_id": "req_…" } }Kenar (nginx) IP sınırları
Üretim yığınındaki nginx, kaynak IP başına ek sınır uygular (limit_req, aşımda 429):
| Bölge | Yollar | Hız | Burst |
|---|---|---|---|
api_ip | /v1/* | 200 r/s | 400 |
sdk_ip | /sdk/v1/* | 60 r/s | 120 |
auth_ip | kayıt/giriş/parola uçları | 5 r/s | 10 |
Vekil arkasında gerçek IP için TRUST_PROXY yapılandırılır (XFF sahteciliğiyle sınır ya da IP izin listesi atlatılamaz).
Plan kotaları
Kota aşımında 429 HS_QUOTA_EXCEEDED (details.metric, limit, used); özellik planda yoksa 403 HS_PLAN_FEATURE_REQUIRED (details.feature, details.plan). Kullanım: GET /v1/organization/usage ve dashboard Faturalama → Kullanım. Deneme süresi ve askıya alma kuralları: planlar ve kota.
Yeniden deneme önerileri
429ve5xxiçinRetry-After/X-RateLimit-Resetkadar bekleyip üstel geri çekilme + jitter ile yeniden deneyin;4xx(429 hariç) yeniden denenmez.- Sunucu SDK'ları bunu otomatik yapar (
maxRetries, varsayılan 3) ve idempotent işlemlerde aynıIdempotency-Key'i kullanır. - Toplu işlemler için uçların toplu biçimlerini kullanın:
POST /v1/apps/{app_id}/events(olay dizisi),target.include_external_ids(≤ 2000), CSV içe aktarma; tek tek çağrı yerineusers.upsert+subscriptionsdizisi. - Liste uçlarında
limiten fazla 200; sayfalama içincursor(sayfalama). - Webhook ile olayları almak, durum sorgulamak için yoklama yapmaktan daha verimlidir (webhook'lar).
Kimlik doğrulama
Public API için Bearer API anahtarı, kapsam ve app/org bağlamı; istemci SDK uçlarında sahiplik kanıtı (token_hash) ve identity verification (identity_hash HMAC ya da ES256 JWT); hata yanıtları.
Idempotency
Idempotency-Key başlığı ve idempotency_key alanı, 24 saatlik saklama, aynı/farklı gövde davranışı, sürmekte olan istek kirası, hangi işlemlerin desteklediği ve SDK'lardaki otomatik anahtar.