Rate limits

Per-API-key request limits, what a 429 looks like, and how to stay under the limits

Requests are rate-limited per API key over a rolling one-minute window. The limit that applies depends on what the request does:

Tier	Applies to	Limit
Reads	All GET requests	300 / minute
Mutations	POST, PATCH, DELETE	60 / minute
OTP resend	PATCH /request/resend/{requestId}	20 / minute

The tier is selected automatically from the request — reads and mutations don’t share a bucket, so heavy polling doesn’t starve your writes (or vice versa).

When you exceed a limit

The API responds with 429 Too Many Requests:

{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Nothing is queued — the request was not processed. Retry after backing off; the window is one minute, so a short exponential backoff (for example 1s → 2s → 4s, capped at 30s) recovers quickly.

Staying under the limits

• Prefer webhooks over polling. Every request outcome is pushed to your webhook endpoint; a poll loop against GET /request/{id} spends read budget to learn what a webhook would have told you immediately.
• Page deliberately. List endpoints accept pageSize up to 100 — one page of 100 costs a single read, not ten pages of 10.
• Treat the resend limit as a safety rail. PATCH /request/resend delivers a new OTP to a real person; 20/minute is deliberately tight to protect recipients from notification storms.
• One key per integration. Limits are per key, so separate workloads (e.g. a backend service and an internal script) don’t compete if they use their own keys.

Limits may be tuned over time; treat the numbers above as the current defaults rather than a contract. If your integration legitimately needs more, contact us.