To ensure stability and fair usage of our services, Caret limits the number of requests a client can make to our API within a specific time period. Rate limits are applied per API key and vary based on the endpoint and your subscription plan.

​
Default Limits

PlanRequests per MinuteWebhooks per Minute
Free6020
Pro12040
Enterprise300100
Some resource-intensive operations may have lower specific limits, which will be documented in the relevant API reference section.

​
Rate Limit Headers

When you make an API request, Caret includes several headers in the response to help you track your rate limit usage:
HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed in the current time window
X-RateLimit-RemainingThe number of requests remaining in the current time window
X-RateLimit-ResetThe time at which the current rate limit window resets, in Unix time
Example response headers: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1672527600

​
Handling Rate Limit Errors

If you exceed the rate limit, the API will respond with a 429 Too Many Requests status code. The response body will contain an error message explaining the situation. Example rate limit error response: 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 35 seconds.",
    "retry_after": 35
  }
}

​
Best Practices for Handling Rate Limits

  1. Implement Exponential Backoff: When you receive a 429 response, wait for the time specified in the retry_after field before retrying.
  2. Monitor Your Usage: Track the rate limit headers in each response to monitor your usage and adjust your request rate accordingly.
  3. Cache Responses: Whenever possible, cache API responses to reduce the number of requests you need to make.
  4. Batch Operations: If you need to perform multiple operations, use batch endpoints where available to reduce the number of requests.

​
Example Retry Logic

Here’s an example of how to implement retry logic with exponential backoff in JavaScript: 
async function fetchWithRetry(url, options, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      const response = await fetch(url, options);

      if (response.status !== 429) {
        return response;
      }

      const data = await response.json();
      const retryAfter = data.error.retry_after || Math.pow(2, retries);

      console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));

      retries++;
    } catch (error) {
      if (retries === maxRetries - 1) {
        throw error;
      }

      const backoffTime = Math.pow(2, retries) * 1000;
      console.log(
        `Error: ${error.message}. Retrying after ${backoffTime / 1000} seconds...`,
      );
      await new Promise((resolve) => setTimeout(resolve, backoffTime));

      retries++;
    }
  }

  throw new Error('Maximum retries reached');
}

​
Increasing Rate Limits

If you need higher rate limits than what your current plan provides, consider:
  1. Upgrading Your Plan: Higher-tier plans come with higher rate limits.
  2. Contact Support: Enterprise customers can contact our support team to discuss custom rate limits based on your specific needs.

​
Next Steps