Rate Limits

Understand and handle HueChat API rate limits.

Overview

Rate limits protect the API from abuse and ensure fair usage for all customers.

Limits by Plan

Plan	Requests/Minute	Requests/Day
Free	100	10,000
Pro	1,000	100,000
Enterprise	Custom	Custom

Rate Limit Headers

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1706215260

Header	Description
X-RateLimit-Limit	Maximum requests allowed per minute
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": "rate_limited",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "code": 429,
  "retry_after": 60
}

Retry-After Header

The response includes a Retry-After header indicating when to retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Implementation Strategies

1. Check Headers Before Each Request

let remainingRequests = Infinity;
let resetTime = 0;

async function makeRequest(url, options) {
  // Check if we should wait
  if (remainingRequests <= 0) {
    const waitTime = resetTime - Date.now();
    if (waitTime > 0) {
      await sleep(waitTime);
    }
  }

  const response = await fetch(url, options);

  // Update rate limit info
  remainingRequests = parseInt(response.headers.get('X-RateLimit-Remaining'));
  resetTime = parseInt(response.headers.get('X-RateLimit-Reset')) * 1000;

  return response;
}

2. Exponential Backoff

import time
import requests

def make_request_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            wait_time = min(retry_after, 2 ** attempt * 10)
            print(f"Rate limited. Waiting {wait_time} seconds...")
            time.sleep(wait_time)
            continue

        return response

    raise Exception("Max retries exceeded")

3. Request Queuing

class RequestQueue {
  constructor(requestsPerMinute) {
    this.queue = [];
    this.processing = false;
    this.interval = 60000 / requestsPerMinute;
  }

  async add(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.process();
    });
  }

  async process() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;
    const { requestFn, resolve, reject } = this.queue.shift();

    try {
      const result = await requestFn();
      resolve(result);
    } catch (error) {
      reject(error);
    }

    setTimeout(() => {
      this.processing = false;
      this.process();
    }, this.interval);
  }
}

// Usage
const queue = new RequestQueue(100); // 100 requests per minute

async function getContact(id) {
  return queue.add(() =>
    fetch(`https://api.huechat.ai/v2/contact/${id}`, {
      headers: { 'X-API-Key': apiKey }
    })
  );
}

Bulk Operations

For operations involving many records, use bulk endpoints when available:

Instead of This

// Bad: 100 individual requests
for (const contact of contacts) {
  await createContact(contact);
}

Do This

// Good: Single bulk request
await createContacts(contacts);

Endpoint-Specific Limits

Some endpoints have additional limits:

Endpoint	Limit	Notes
/contact/*/message	100/min per contact	Per-contact message rate
/webhooks/*/test	10/min	Test endpoint rate
/admin/analytics/*	20/min	Analytics queries

Monitoring Usage

Track your API usage in the dashboard:

1. Go to Settings > API Usage
2. View requests by:
   • Day/Week/Month
   • Endpoint
   • API Key
   • Status Code

Increasing Limits

Pro Plan

Upgrade to Pro for 10x the rate limits:

• 1,000 requests/minute
• 100,000 requests/day
• Priority support

Enterprise

Contact sales for custom limits:

• Unlimited requests
• Dedicated infrastructure
• SLA guarantees
• Custom endpoint limits

Contact Sales

Best Practices

1. Cache responses when possible
2. Use webhooks instead of polling
3. Batch requests when APIs support it
4. Implement backoff for rate limit errors
5. Monitor usage to predict needs
6. Use test keys for development (separate limits)