Known Limitations & Guarantees
Great platforms document their edges, not just their happy paths. This page is the single, honest list of what to design around before you go to production. Nothing here is a blocker for most integrations, but each item changes how you should build. When in doubt, prefer idempotent handlers and authoritative re-reads.
Delivery & webhooks
| Area | Limitation | How to design for it |
|---|
| Ordering | Webhook deliveries have no ordering guarantee. Retries are independent. | Process events idempotently; never assume order. Use occurred_at in the payload to sequence. |
| Replays | A replayed delivery may carry a redacted data: {} payload. | On replay, re-fetch current state from the API. Do not treat a replayed payload as complete. |
| Secrets | There is no webhook secret rotation endpoint. | To rotate, delete the destination and recreate it with a new secret. |
| Recovery | Exhausted deliveries are terminal; there is no automatic redrive. | Use the manual replay endpoints as your recovery path; monitor the delivery log. |
Freshness & consistency
| Area | Limitation | How to design for it |
|---|
| Leaderboards | General leaderboard reads can be up to ~30s stale (in-process cache). | Do not promise real-time general boards. For a participant’s own live progression, use streaming. |
| Streak days | Streak day boundaries are UTC-only. | Tell users streaks roll over at 00:00 UTC; do not localize the boundary. |
| Points expiry | Points expiry can be defined but the expiry worker is not operational yet. | Do not rely on automatic points expiry in launch-critical logic. |
Scale
- General leaderboards are sized for roughly 100K participants per tenant. Larger boards need a scoped or segmented design; talk to us before relying on a single global board at higher scale.
- Event ingestion is synchronous: rules, facts, and progression are applied before the response returns. This gives you immediate, consistent reads, but very high-volume producers should batch (up to 100 events per batch call) and respect rate limits.
Data & compliance
| Area | Limitation | How to design for it |
|---|
| Participant export | A participant data export endpoint does not exist yet. Erasure does. | Do not promise self-serve export from Bricqs today; keep your own copy of anything you must export. Erasure is available. |
| Notifications | Bricqs does not deliver participant notifications (email/push/in-app). | Bring your own messaging. Webhooks are the trigger source; you send the message. |
SDK & platform boundaries
- No mobile-native SDK. Non-React and native consumers use the REST API directly — a fully supported, first-class path.
- Admin configuration is dashboard-first. Contests, challenges, and campaign configuration are done in the Builder/dashboard, not via a public config API. The public API is for events, reads, participant tokens, rewards, and the admin CRUD that is documented in the API reference.
- Pagination varies by endpoint. Some use
page/page_size, others limit/offset. Read each endpoint’s reference; there is no single global pagination rule. - Branch on
error.type first. Most errors carry a stable error.code, but a few endpoints still surface generic status-derived types. Use type as the primary branch and code when present.
