Rate Limits & Quotas

Per-Endpoint Rate Limits

Limits are enforced per authenticated user (or IP for unauthenticated requests).

Authentication

Endpoint	Method	Limit
/auth/member/register	POST	5/min
/auth/member/login	POST	5/min
/auth/lender/register	POST	5/min
/auth/lender/login	POST	5/min
/auth/2fa/verify-login	POST	5/min
/auth/refresh	POST	5/min
/auth/password-reset/confirm	POST	5/min
/auth/logout	POST	5/min
/auth/password-reset/request	POST	3/hr
/auth/email/resend	POST	3/hr
/auth/lender/rotate-key	POST	3/hr

Credentials

Endpoint	Method	Limit
/credentials/issue	POST	10/min

QR Codes

Endpoint	Method	Limit
/qr/generate	POST	10/min
/qr/resolve	POST	30/min

Verification

Endpoint	Method	Limit
/verify/token	POST	30/min
/verify/proof	POST	30/min
/verify/history	GET	30/min

Webhooks

Endpoint	Method	Limit
/webhooks (create)	POST	10/min
/webhooks (list)	GET	30/min
/webhooks/{id} (delete)	DELETE	30/min

Trust Registry

Endpoint	Method	Limit
/trust-registry	GET	60/min
/trust-registry/{id}	GET	60/min

Admin & Analytics

Endpoint	Method	Limit
/analytics/*	GET	30/min
/admin/*	ALL	30/min

Quota Tiers

Monthly verification quotas by plan:

Plan	Verifications/month	Requests/min
Free	100	10
Standard	5,000	60
Enterprise	Unlimited	300

Check your current usage:

curl https://api.zkprova.com/api/v1/analytics/quota \
  -H "X-API-Key: zkp_live_abc123"

{
  "plan": "standard",
  "monthly_quota": 5000,
  "used": 1247,
  "remaining": 3753,
  "month_key": "2026-02"
}

Response Headers

Every API response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Max requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Seconds until the rate limit window resets

Handling 429 Responses

When rate-limited, the response includes a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{"detail": "Rate limit exceeded. Please try again later."}

When your monthly quota is exhausted:

{"detail": "Monthly quota exceeded. Upgrade your plan or wait until next month."}

SDK Auto-Retry

The TypeScript SDK automatically retries on 429 responses, respecting the Retry-After header:

const client = new ZKProvaClient({
  apiKey: 'zkp_live_abc123',
  retries: 3,  // retries on 429 and 5xx (default: 3)
});

// Check remaining quota programmatically
const quota = await client.getQuotaStatus();
if (quota.remaining < 10) {
  console.warn('Quota almost exhausted');
}