frequentix
Developer docs

Build on the same API the product runs on.

The storefront, console and scanner are all clients of the frequentix API. These pages document the surface you can use too — OAuth clients, REST reads and signed webhooks — with worked examples our test suite verifies.

Documentation menu

Errors & rate limits

Errors are JSON with a human-readable message. Seven status codes cover the integration surface.

Status codes

400A write was sent without the Idempotency-Key header it requires.

Send a unique key (a UUID is ideal) with every write.

401Missing, expired or revoked token.

Mint a fresh token at the token endpoint and retry once.

403The token lacks the scope the endpoint requires — or a plan gate refused the action (plan.upgrade_required, naming the capability).

Check the client’s scopes in the console, and the scope you request when minting.

404Unknown reference or slug — or a real event outside your client’s event scope. The two are deliberately indistinguishable, so existence is never revealed.

Verify the key and the client’s event access; don’t retry a 404 blindly.

409An Idempotency-Key was reused with a different request body, or the first attempt is still in flight.

Mint a fresh key for genuinely new requests; replay the original body to retrieve the stored response.

422Validation failed — or, on check-in, a denied verdict: the same shape as a 200 with allowed: false and a reason.

Read errors for field problems; on /integration/scans, branch on allowed rather than the status alone.

429Rate limit exceeded.

Honour Retry-After and back off; spread bulk reads rather than bursting.

Rate limits

The API allows 120 requests per minute per integration client — shared across all of a client’s tokens, so rotating tokens never widens the budget. Standard rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are returned on every response, and a 429 carries Retry-After.

  • Prefer webhooks to polling — they exist so you don’t have to spend the budget asking “anything new?”.
  • For bulk reads, walk pages sequentially via next_page_url; parallel page-hammering just meets the limiter sooner.

Pagination

List endpoints page at 25 per page by default; ?per_page= raises that to at most 100. The paginator envelope — and the cursor envelope served in incremental mode — is documented in the API reference. A page never costs more budget for being fuller, so fewer, larger pages are the rate-limit-friendly shape for bulk reads.