Rate Limits

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:

{
  "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

Testing

Getting Started

Essentials

Transaction Flows

Limit Tiers

When You’re Rate Limited

Integrator Exemptions

Best Practices

​Limit Tiers

​When You’re Rate Limited

​Integrator Exemptions

​Best Practices

Limit Tiers

When You’re Rate Limited

Integrator Exemptions

Best Practices