API Rate Limits

To ensure platform stability and fair usage for all users, the BotSubscription API enforces rate limits on all endpoints.

Current Limits

These limits apply across all endpoints. Some endpoints may have additional restrictions noted in their documentation.

Rate Limit Headers

Every API response includes headers to help you track your usage:

Exceeding Limits

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

{
  "request_id": "uuid",
  "method": "GET",
  "path": "/api/users",
  "code": 429,
  "error": {
    "message": "Rate limit exceeded. Please retry after 32 seconds.",
    "code": "RATE_LIMIT_EXCEEDED",
    "retry_after": 32
  }
}

The Retry-After header indicates how many seconds to wait before retrying.

Best Practices

1. Implement Exponential Backoff

When you receive a 429 response, wait before retrying. Use exponential backoff to avoid hammering the API:

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

2. Cache Responses

Avoid redundant API calls by caching data that doesn't change frequently:

• Plans: Cache for 5-10 minutes (rarely change)
• User data: Cache for 1-2 minutes
• Settings: Cache for 5 minutes

3. Use Webhooks Instead of Polling

Instead of polling for updates, configure webhooks to receive real-time notifications when events occur.

4. Batch Operations Where Possible

Some endpoints support batch operations. Use them to reduce the number of API calls:

• Use PATCH /settings to update multiple settings at once
• Use PATCH /targets to update multiple targets at once

5. Monitor Your Usage

Check the rate limit headers in responses to monitor your usage and adjust your request patterns before hitting limits.

Temporary Suspension

Repeated or excessive rate limit violations may result in temporary API access suspension. If you need higher limits for a legitimate use case, contact support.

WebSocket Alternative

For real-time data, consider using our WebSocket endpoint instead of polling the REST API. WebSocket connections are not subject to REST API rate limits.