Rate Limiting

The Cliq API uses rate limiting to ensure fair usage and maintain service quality for all users.

Rate Limits

Default Limits

Plan	Requests per Minute	Requests per Day
Free	60	1,000
Pro	300	10,000
Enterprise	1,000	100,000

Per-Endpoint Limits

Some endpoints have additional limits:

Endpoint	Limit
POST /issues	30/minute
POST /comments	60/minute
GET /search	30/minute
Bulk operations	10/minute

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705312800

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}

Best Practices

1. Implement Exponential Backoff

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      await sleep(retryAfter * 1000 * Math.pow(2, i));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

2. Cache Responses

Reduce API calls by caching responses:

const cache = new Map();

async function getIssue(id: string) {
  const cacheKey = `issue:${id}`;
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const issue = await cliq.issues.get(id);
  cache.set(cacheKey, issue);
  
  return issue;
}

3. Use Bulk Operations

Instead of making multiple individual requests, use bulk endpoints:

// ❌ Don't do this
for (const issue of issues) {
  await cliq.issues.update(issue.id, issue);
}

// ✅ Do this instead
await cliq.issues.bulkUpdate(issues);

4. Monitor Your Usage

Check your current usage in the dashboard:

Go to Settings → API
View Usage Statistics
Set up alerts for approaching limits

Webhooks for Real-Time Updates

Instead of polling the API, use webhooks to receive real-time updates:

// ❌ Polling (uses many requests)
setInterval(async () => {
  const issues = await cliq.issues.list({ updated_after: lastCheck });
  // Process updates
}, 5000);

// ✅ Webhooks (no requests needed)
app.post('/webhook', (req, res) => {
  const event = req.body;
  // Process update immediately
  res.sendStatus(200);
});

Requesting Higher Limits

If you need higher rate limits:

Pro Plan - Upgrade to Pro for 5x the limits
Enterprise Plan - Contact sales for custom limits
Temporary Increase - Contact support for one-time migrations

Monitoring and Alerts

Set up monitoring to track your API usage:

async function makeRequest(url: string, options: RequestInit) {
  const response = await fetch(url, options);
  
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
  const limit = parseInt(response.headers.get('X-RateLimit-Limit') || '0');
  
  // Alert when 80% of limit is used
  if (remaining < limit * 0.2) {
    console.warn(`Rate limit warning: ${remaining}/${limit} remaining`);
  }
  
  return response;
}

Rate Limiting

On this page