Rate Limits

The Clio Platform API enforces rate limits to ensure fair usage and maintain service reliability for all integrators. This document explains how rate limiting works, what to expect when limits are exceeded, and best practices for building resilient integrations.

How Rate Limiting Works

Rate limits are applied per OAuth application. This means the total number of requests made by your application across all users is subject to a shared limit. Each request your application makes—regardless of which user's access token is used—counts toward your application's rate limit quota.

Default Rate Limits

All applications are assigned a default rate limit of 3 requests per second.

Rate Limit Response

When your application exceeds its rate limit, the API returns an HTTP 429 Too Many Requests response.

Response Body

The response body contains an error message:

{
  "message": "Too Many Requests"
}

Handling Rate Limits

Your application should be designed to handle rate limiting gracefully. Here are the recommended approaches:

1. Implement Exponential Backoff

When you receive a 429 response, use exponential backoff to retry the request:

async function makeRequestWithRetry(requestFn, maxRetries = 5) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      const response = await requestFn();

      if (response.status === 429) {
        // Exponential backoff: 1s, 2s, 4s, 8s, 16s
        const waitTime = Math.pow(2, retries) * 1000;

        await new Promise(resolve => setTimeout(resolve, waitTime));
        retries++;
        continue;
      }

      return response;
    } catch (error) {
      throw error;
    }
  }

  throw new Error('Max retries exceeded');
}

2. Implement Request Queuing

For high-volume applications, implement a request queue that respects rate limits:

Rate Limit Errors vs Other Errors

HTTP Status	Error Type	Meaning	Action
429	Rate Limited	Too many requests	Wait and retry with backoff
401	Unauthorized	Invalid or expired token	Refresh token or re-authenticate
403	Forbidden	Insufficient permissions	Check OAuth scopes
500	Server Error	Internal error	Retry with backoff

FAQ

Are rate limits shared across regions?

No. Each Clio region (US, CA, EU, AU) has separate rate limiting. Your application's API calls to one region do not affect your limits in other regions.

What if I need higher limits?

We do not support custom rate limit increases for applications at this time.

See Also

• ETags - Reduce unnecessary requests with conditional fetching
• Pagination - Efficiently retrieve large datasets