Rate Limiting

The Kula API allows 1,000 requests per hour per account. All API tokens on the same account share this limit.

Response Headers

Every response includes rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests per hour
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	Unix timestamp when limit resets

Rate Limit Exceeded

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

{
  "error": {
    "code": "ERR_RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  },
  "meta": {
    "retry_after": 300
  }
}

Wait for retry_after seconds before retrying.

Handling Rate Limits

Check the response status and implement retry logic:

async function makeRequest(url, token) {
  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  if (response.status === 429) {
    const retryAfter = response.headers.get('retry-after') || 60;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return makeRequest(url, token);
  }

  return response.json();
}

Best Practices

Do	Don't
Cache responses	Poll frequently
Use webhooks for updates	Fetch all pages unnecessarily
Monitor remaining requests	Ignore rate limit headers
Request only needed data	Make redundant requests

Increasing Limits

Enterprise plans include higher limits. Contact api-support@kula.ai for details.