Rate Limits

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

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:

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

• Understand error handling