Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.kotanipay.com/llms.txt

Use this file to discover all available pages before exploring further.

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 a different request limit and window. A separate burst limit also applies across all tiers — it catches 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 updates — polling is the most common cause of hitting rate limits
  • If you need to check many records, use list endpoints with pagination rather than looping individual lookups
  • Back off and retry when you receive a 429 — use the retryAfter value from the response