Skip to main content
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:
TierApplied to
GeneralStandard create and update operations
SensitiveAuthentication and security-critical endpoints
Read-onlyGET 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