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

# Rate Limits

> How the Kotani Pay API rate limits requests and what to expect when you exceed them

The Kotani Pay API uses a Redis-backed sliding window rate limiter applied per endpoint, per API key. Limits are not fixed globally — they vary by endpoint sensitivity and are configurable per integrator.

***

## Limit Tiers

Endpoints are grouped into three tiers:

| Tier          | Applied to                                     |
| ------------- | ---------------------------------------------- |
| **General**   | Standard create and update operations          |
| **Sensitive** | Authentication and security-critical endpoints |
| **Read-only** | GET and list endpoints                         |

Each tier has its own request limit and window duration. A separate burst limit applies across all tiers, catching rapid-fire requests within any 5-second window regardless of the per-minute count.

***

## When You're Rate Limited

When you exceed a limit, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "statusCode": 429,
  "message": "Too many requests. You have exceeded the limit of N requests per X seconds. Please wait before trying again.",
  "error": "Too Many Requests",
  "data": {
    "retryAfter": 60
  }
}
```

The `data.retryAfter` value is in seconds. Wait at least that long before retrying.

***

## Integrator Exemptions

High-volume integrators can be placed on an exempt list that bypasses rate limiting entirely. Contact your account manager if your use case requires this.

***

## Best Practices

* Use webhooks instead of polling for transaction status — polling is the most common cause of hitting rate limits
* When checking many records, use list endpoints with pagination rather than looping individual lookups
* When you receive a `429`, back off and retry using the `retryAfter` value from the response