Rate Limiting

The Mandaitor API enforces rate limits to ensure fair usage and protect service stability. This guide explains the rate limiting model, the limits for each plan, and how to handle rate limit errors in your application.

How Rate Limiting Works

Mandaitor uses a token bucket model implemented through AWS API Gateway usage plans. Each API key is associated with a usage plan that defines:

• Rate limit: The sustained number of requests per second allowed.
• Burst limit: The maximum number of concurrent requests allowed in a short burst.
• Monthly quota: The total number of requests allowed per calendar month.

When you exceed the rate limit, the API returns a 429 Too Many Requests response. When you exceed the monthly quota, all requests are rejected until the quota resets at the beginning of the next month.

Usage Plans

Mandaitor currently offers two usage plans:

Beta Plan

The standard plan for beta testers and early adopters.

Limit	Value
Rate limit	50 requests/second
Burst limit	100 requests
Monthly quota	50,000 requests

Enterprise Plan

For strategic partners requiring higher throughput.

Limit	Value
Rate limit	200 requests/second
Burst limit	400 requests
Monthly quota	500,000 requests

To upgrade to the Enterprise plan, contact us at support@mandaitor.io.

Per-Endpoint Limits

In addition to the global rate limits, certain endpoints have stricter per-method limits to protect expensive or sensitive operations:

Endpoint	Beta Plan	Enterprise Plan	Rationale
POST /mandates	5 req/s, burst 10	25 req/s, burst 50	Each creation involves KMS signing
POST /mandates/{id}/revoke	10 req/s, burst 20	30 req/s, burst 60	Lifecycle state change + audit event
POST /mandates/{id}/suspend	10 req/s, burst 20	30 req/s, burst 60	Lifecycle state change + audit event
POST /mandates/{id}/reactivate	10 req/s, burst 20	30 req/s, burst 60	Lifecycle state change + audit event
POST /onboarding/request	2 req/s, burst 5	2 req/s, burst 5	Public endpoint, tightly limited
POST /tenants/{id}/api-keys	1 req/s, burst 3	3 req/s, burst 9	Sensitive, rare operation
POST /verify	Global limit	Global limit	Read-only, no per-method restriction
GET /mandates, GET /events	Global limit	Global limit	Read-only, no per-method restriction

Handling Rate Limit Errors

When you exceed the rate limit, the API returns:

{
  "error": "TOO_MANY_REQUESTS",
  "message": "Rate limit exceeded"
}

Recommended approach: Exponential backoff

Implement exponential backoff with jitter to gracefully handle rate limiting:

async function withBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      const status = error?.status ?? error?.response?.status;
      if (status !== 429 || attempt === maxRetries) throw error;

      const delay = baseDelay * Math.pow(2, attempt);
      const jitter = delay * 0.5 * Math.random();
      await new Promise((r) => setTimeout(r, delay + jitter));
    }
  }
  throw new Error("Unreachable");
}

Best practices for staying within limits

1. Batch where possible: If you need to create multiple mandates, space out the requests rather than sending them all at once.

2. Cache verification results: If you verify the same action repeatedly within a short time window, cache the result on your side instead of calling the API each time.

3. Use read endpoints efficiently: Use the limit and cursor pagination parameters to fetch only the data you need.

4. Monitor your usage: Track your request count against your monthly quota. If you are consistently approaching the limit, consider upgrading your plan.

Quota Reset

Monthly quotas reset at the beginning of each calendar month (UTC). There is no way to manually reset the quota within a billing period.

Need Higher Limits?

If your use case requires higher rate limits or a larger monthly quota, contact us at support@mandaitor.io to discuss the Enterprise plan or a custom arrangement.