Rate Limits

API rate limits, monitoring usage, and handling rate limit errors

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

Plan	Requests per Minute	Webhooks per Minute
Free	60	20
Pro	120	40
Enterprise	300	100

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:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed in the current time window
X-RateLimit-Remaining	The number of requests remaining in the current time window
X-RateLimit-Reset	The 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

• Understand error handling