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.

This limit is sufficient for most integrations. If your application requires higher limits, contact api@clio.com to request an increase.

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:

Best Practices

Monitor Your Usage

Keep track of your API usage patterns to identify potential issues before hitting rate limits:

• Log all 429 responses with timestamps
• Track request counts per endpoint
• Set up alerts when approaching your rate limit threshold

Optimize Your Integration

Reduce unnecessary API calls by:

• Caching responses: Store data locally when appropriate and use ETags for conditional requests
• Using webhooks: Subscribe to webhooks instead of polling for updates
• Batching requests: Group related operations when possible
• Requesting only needed fields: Use the fields parameter to limit response data

Handle Errors Gracefully

Design your application to degrade gracefully when rate limited:

• Queue non-critical operations for later retry
• Show meaningful messages to users when actions are delayed
• Avoid retry storms by implementing proper backoff strategies

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?

Contact api@clio.com to request a rate limit increase. Include details about:

• Your application's purpose
• Expected request volume
• Which endpoints you use most frequently

See Also

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