> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masterid.co.ug/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> MasterID API rate limits, how to handle 429 responses, and client-side throttling examples in Node.js and Python.

MasterID enforces per-workspace rate limits to protect platform stability. Designs your integration to stay within limits and to back off correctly when throttled.

## Limit table

| Scope | Limit | Window |
| - | - | - |
| Authenticated API requests | 60 requests | per minute |
| Payment requests (collections) | 40 requests | per hour |
| Payment requests (collections) | 200 requests | per day |
| Payment requests per phone number | 3 requests | per 15 minutes |
| Payment requests per phone per workspace | 8 requests | per day |
| Payment requests per phone across MasterID | 10 requests | per day |

> [!NOTE]
>
> These are MasterID platform limits, not guarantees of throughput.

## 429 response

When a limit is reached, MasterID returns HTTP 429 and a `Retry-After` header indicating how many seconds to wait before retrying.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 45
Content-Type: application/json

{ "id": "<REQUEST_ID>", "error": "API request limit reached" }
```

> [!WARNING]
>
> Do not retry immediately on 429. Always read `Retry-After` and wait the full duration.

## Client-side throttle example

Implement a simple token bucket or delay tracker to avoid hitting the limit during bursts.

```typescript throttle.ts theme={null}
class MasterIDThrottler {
  private lastRequestTime = 0;
  private minIntervalMs: number;

  constructor(requestsPerMinute: number) {
    this.minIntervalMs = 60_000 / requestsPerMinute;
  }

  async ready(): Promise<void> {
    const now = Date.now();
    const elapsed = now - this.lastRequestTime;
    const delay = Math.max(0, this.minIntervalMs - elapsed);
    if (delay > 0) {
      await new Promise((r) => setTimeout(r, delay));
    }
    this.lastRequestTime = Date.now();
  }
}

const throttler = new MasterIDThrottler(60);

async function throttledCall(path: string, init?: RequestInit) {
  await throttler.ready();
  return fetch(`https://masterid.me/api/public/v1${path}`, {
    ...init,
    headers: {
      "X-API-Key": process.env.MASTERID_API_KEY!,
      "X-API-Secret": process.env.MASTERID_API_SECRET!,
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });
}
```

```python throttle.py theme={null}
import os
import time
import requests

BASE_URL = "https://masterid.me/api/public/v1"


class MasterIDThrottler:
    def __init__(self, requests_per_minute: int):
        self.min_interval = 60.0 / requests_per_minute
        self.last_request_time = 0.0

    def ready(self):
        now = time.time()
        elapsed = now - self.last_request_time
        delay = max(0.0, self.min_interval - elapsed)
        if delay:
            time.sleep(delay)
        self.last_request_time = time.time()


throttler = MasterIDThrottler(requests_per_minute=60)


def throttled_call(path, method="GET", **kwargs):
    throttler.ready()
    headers = {
        "X-API-Key": os.environ["MASTERID_API_KEY"],
        "X-API-Secret": os.environ["MASTERID_API_SECRET"],
        "Content-Type": "application/json",
    }
    headers.update(kwargs.pop("headers", {}))
    return requests.request(
        method,
        f"{BASE_URL}{path}",
        headers=headers,
        **kwargs,
    )
```

## Polling budget

When polling for pending verification results, do not call `GET /verifications/{sessionId}` more frequently than every 15 seconds. Faster polling wastes your request budget and can trigger 429.

> [!TIP]
>
> Combine webhooks with occasional polling as a recovery path. Webhooks do not count toward API rate limits.


## Related topics

- [API Overview](https://docs.masterid.co.ug/api-reference/overview.md)
- [Collect mobile money payments](https://docs.masterid.co.ug/guides/payment-collection.md)
- [POST /collections](https://docs.masterid.co.ug/api-reference/collections/create-collection.md)
- [GET /catalog](https://docs.masterid.co.ug/api-reference/catalog/get-catalog.md)
- [GET /wallet](https://docs.masterid.co.ug/api-reference/wallet/get-wallet.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.