API rate limits

AIsoule enforces rate limits to ensure platform stability. Here's how they work.

Default limits

These limits apply per API key.

Rate limit headers

Every API response includes these headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1716984000

• Limit — Your total allowed requests per window
• Remaining — How many requests you have left
• Reset — Unix timestamp when the window resets

Handling 429 (Too Many Requests)

When you exceed the limit, you'll receive:

HTTP 429 Too Many Requests
{
  "message": "Rate limit exceeded. Try again in 30 seconds.",
  "status": "error"
}

Recommended retry strategy

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

Best practices for high-volume usage

1. Batch operations

Instead of creating contacts one-by-one, use bulk endpoints:

POST /api/contacts/bulk

2. Implement exponential backoff

Retry 1: wait 1 second
Retry 2: wait 2 seconds
Retry 3: wait 4 seconds
Retry 4: wait 8 seconds

3. Cache responses

Don't fetch the same data repeatedly. Cache contact lists, templates, etc. locally.

4. Use webhooks instead of polling

Instead of checking for new messages every second, set up webhooks to receive them in real-time.

5. Spread requests over time

If you need to send 1,000 messages, spread them over 10 minutes (100/min) instead of all at once.

Meta's limits (separate from AIsoule)

In addition to AIsoule's API limits, Meta has its own:

• Messaging limits — Unique contacts per day (tier-based)
• Template submission — Max 100 templates per hour
• Media upload — Max 500 uploads per day

These are enforced by Meta regardless of AIsoule's limits.

Need higher limits?

Contact support if you need increased rate limits for your use case. Enterprise plans may include higher limits.