Rate Limits - Kotani Pay

To ensure fair usage and system stability, the Kotani Pay API implements rate limiting on all endpoints.

Rate Limit Structure

The API uses a sliding window rate limit with the following defaults:

Production: 1000 requests per minute per API key
Sandbox: 100 requests per minute per API key

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642234800

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window
`X-RateLimit-Remaining`	Number of requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

Handling Rate Limits

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

{
  "status": "error",
  "message": "Rate limit exceeded",
  "error_code": "RATE_LIMITED",
  "retry_after": 60
}

Best Practices

Monitor rate limit headers in your responses
Implement exponential backoff when rate limited
Cache responses when possible to reduce API calls
Batch operations where the API supports it
Use webhooks instead of polling for status updates

Example: Handling Rate Limits

async function makeAPIRequest(url, options) {
  try {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After") || 60;
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      return makeAPIRequest(url, options); // Retry
    }

    return response;
  } catch (error) {
    console.error("API request failed:", error);
    throw error;
  }
}