Skip to main content

Idempotency and Rate Limits

Idempotency​

  • Bundle deduplication: provide external_ref on create. The API will accept identical replays safely.
  • Video identification: use position (1..N) within a bundle, or your own external_ref when available.
  • Wallet debits/credits: processed idempotently on the server with unique transaction keys.

Rate limits​

TokPortal uses a lightweight, fixed-window throttling per API key, endpoint and client IP.

  • Default policy: 60 requests per minute per API key / endpoint / IP.
  • Per-endpoint overrides: you can request custom limits, for example 20/min on create endpoints and 120/min on read/state endpoints.
  • Overages: excess requests receive 429 Too Many Requests with Retry-After seconds.
  • Response headers: X-RateLimit-Limit (window quota), X-RateLimit-Remaining (remaining in window), Retry-After (seconds to wait).

Implementation note (server-side):

  • Minimal overhead: one SQL operation per request (UPSERT) to track counters, which provides a fast and simple enforcement mechanism without heavy in-memory coordination.