Rate Limits & Quotas
Two independent systems protect the platform: short-window RATE LIMITS (per key, tenant, IP, participant) and monthly PLAN QUOTAS (MAU, API requests, resource counts). Both reject with the standard error envelope and machine-readable codes.
Rate-limit tiers
| Scope | Default limit | Window | 429 code |
|---|---|---|---|
| API key | 1,000 requests (per-key configurable at mint) | 60s | RATE_LIMIT_API_KEY_EXCEEDED |
| Tenant (aggregate) | 5,000 requests | 60s | RATE_LIMIT_TENANT_EXCEEDED |
| IP (general endpoints) | 100 requests | 60s | RATE_LIMIT_IP_EXCEEDED |
| Ingestion burst (IP) | 100 requests | 1s | RATE_LIMIT_BURST_EXCEEDED |
| Ingestion IP (minute) | 5,000 requests (deliberately generous; the burst tier is the sharp edge) | 60s | RATE_LIMIT_INGEST_IP_EXCEEDED |
| Ingestion tenant | Plan’s api_rate_limit_per_minute; 5,000 default | 60s | RATE_LIMIT_INGEST_TENANT_EXCEEDED |
| Participant (events) | 100 events (plan-configurable) | 60s | RATE_LIMIT_PARTICIPANT_EXCEEDED |
- The ingestion endpoints (
/gamify/eventsand batch) run the ingestion tiers (burst + ingest-IP + per-key + ingest-tenant + participant); all other endpoints run the general tiers (IP + per-key + tenant). - Every 429 carries
Retry-AfterplusX-RateLimit-*headers. Respect Retry-After first, then exponential backoff with jitter. - Batched events count individually against the participant limit; over-limit items are marked
rate_limitedin the batch results while the rest of the batch processes. Batching is not a throttling bypass. - Auth endpoints have a stricter per-IP limit (10/min) against credential stuffing.
Plan quotas
Metered monthly quotas (active participants, API requests) and resource caps (badges, challenges, contests per tenant) depend on your plan. Rejections use type plan_limit_exceeded with codes PLAN_MAU_EXCEEDED, PLAN_API_QUOTA_EXCEEDED, PLAN_RESOURCE_LIMIT, and PLAN_FEATURE_DISABLED; the details object carries the resource, current usage, and the cap.
Non-exempt responses include usage headers: X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset, X-Quota-Resource. Log them; they are the cheapest early warning you have.
Plan readback: GET /gamify/plan
Programmatic view of your tier, feature flags, and quota usage, served from the same source enforcement reads. Auth: API key with gamify:read (mint default) or a participant JWT. SDK: useTenantPlan().
curl https://api.bricqs.co/api/v1/gamify/plan -H "X-API-Key: bq_live_..."
{
"tier": "growth",
"features": { "contests_enabled": true, ... },
"quotas": {
"monthly_active_participants": { "used": 8420, "limit": 10000, "reset_at": "..." },
"monthly_api_requests": { "used": 412300, "limit": 1000000, "reset_at": "..." },
"badges": { "used": 18, "limit": 50 }
},
"next_tier": { "code": "scale", "unlocks": [...] }
}