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 and per endpoint over a fixed one-minute window. The limit that applies depends on what the request does:

Tier	Applies to	Limit
Reads	All GET requests, plus POST /credential/vp/{vcId} and POST /credential/verify	300 / minute
Mutations	Other POST, PATCH, DELETE requests	60 / minute
OTP resend	PATCH /request/resend/{requestId}	20 / minute

The tier is selected automatically from the request, and each endpoint keeps its own counter, so heavy polling on one endpoint doesn’t starve another endpoint or your writes.

When you exceed a limit

The API responds with 429 Too Many Requests and a Retry-After header (in seconds):

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

Nothing is queued: the request was not processed. Once you exceed a limit, that endpoint stays blocked for up to 60 seconds; wait the number of seconds in Retry-After before retrying.

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.