PushizoDocs
API reference

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):

Planapi_rpsSubscribersMessages / monthAppsMembersRetention
Free2010,000100,0001330 days
Starter10050,0001,000,00031090 days
Growth500500,00010,000,0001050365 days
Enterprise2,000unlimitedunlimitedunlimitedunlimited730 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:

HeaderMeaning
X-RateLimit-LimitBucket capacity (number of burst requests allowed)
X-RateLimit-RemainingRemaining allowance in the bucket
X-RateLimit-ResetSeconds 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):

ZonePathsRateBurst
api_ip/v1/*200 r/s400
sdk_ip/sdk/v1/*60 r/s120
auth_ipsign-up/sign-in/password endpoints5 r/s10

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 429 and 5xx, wait for Retry-After/X-RateLimit-Reset and retry with exponential backoff + jitter; 4xx (except 429) is not retried.
  • The server SDKs do this automatically (maxRetries, default 3) and reuse the same Idempotency-Key for 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 + a subscriptions array instead of individual calls.
  • On list endpoints limit is at most 200; use cursor for pagination (pagination).
  • Receiving events via webhooks is more efficient than polling for status (webhooks).

On this page