Rate limits and quotas
Plan-based API request rate (api_rps), X-RateLimit headers, 429 and Retry-After behavior, per-endpoint limits, nginx IP limits, plan quotas and SDK retry rules.
Pushizo enforces limits at two layers: an in-app token bucket (per API key/actor, in Redis) and an IP-based nginx limit at the edge. Plan quotas (subscribers, monthly messages, apps, members) are a separate mechanism.
Plan-based request rate
For requests made with an API key, the bucket capacity is the plan's api_rps value (refilled per second):
| Plan | api_rps | Subscribers | Messages / month | Apps | Members | Retention |
|---|---|---|---|---|---|---|
| Free | 20 | 10,000 | 100,000 | 1 | 3 | 30 days |
| Starter | 100 | 50,000 | 1,000,000 | 3 | 10 | 90 days |
| Growth | 500 | 500,000 | 10,000,000 | 10 | 50 | 365 days |
| Enterprise | 2,000 | unlimited | unlimited | unlimited | unlimited | 730 days |
Values are read from the plan matrix (plans and quotas); plan definitions can be changed in your own installation. Some endpoints carry their own, tighter limit (e.g. personal data download 5 requests / 5 min, SDK error reports, sign-up/sign-in).
Response headers
Every response carries these headers:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Bucket capacity (number of burst requests allowed) |
X-RateLimit-Remaining | Remaining allowance in the bucket |
X-RateLimit-Reset | Seconds until the bucket is full again (for a 429, until you can retry) |
When exceeded:
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_…" } }Edge (nginx) IP limits
nginx in the production stack applies an additional limit per source IP (limit_req, 429 when exceeded):
| Zone | Paths | Rate | Burst |
|---|---|---|---|
api_ip | /v1/* | 200 r/s | 400 |
sdk_ip | /sdk/v1/* | 60 r/s | 120 |
auth_ip | sign-up/sign-in/password endpoints | 5 r/s | 10 |
Behind a proxy, configure TRUST_PROXY to get the real IP (limits and IP allowlists cannot be bypassed by XFF spoofing).
Plan quotas
When a quota is exceeded you get 429 HS_QUOTA_EXCEEDED (details.metric, limit, used); if a feature isn't included in the plan, 403 HS_PLAN_FEATURE_REQUIRED (details.feature, details.plan). Usage: GET /v1/organization/usage and the dashboard under Billing → Usage. Trial period and suspension rules: plans and quotas.
Retry recommendations
- For
429and5xx, wait forRetry-After/X-RateLimit-Resetand retry with exponential backoff + jitter;4xx(except 429) is not retried. - The server SDKs do this automatically (
maxRetries, default 3) and reuse the sameIdempotency-Keyfor idempotent operations. - For bulk work, use the endpoints' batch forms:
POST /v1/apps/{app_id}/events(event array),target.include_external_ids(≤ 2000), CSV import;users.upsert+ asubscriptionsarray instead of individual calls. - On list endpoints
limitis at most 200; usecursorfor pagination (pagination). - Receiving events via webhooks is more efficient than polling for status (webhooks).
Authentication
Bearer API keys, scopes and app/org context for the public API; proof of ownership (token_hash) and identity verification (identity_hash HMAC or ES256 JWT) on client SDK endpoints; error responses.
Idempotency
The Idempotency-Key header and idempotency_key field, 24-hour retention, same/different body behavior, the in-progress request lease, which operations support it, and automatic keys in the SDKs.