API Rate Limits & Throttling

To safeguard the performance and integrity of our messaging engines, the AISoule REST API implements strict rate limits.

Default Limits

Rate limits are calculated on a per-API key basis, refreshed in rolling windows:

• Standard REST API routes: 120 requests per minute (2 requests/sec).
• Messaging endpoints (/v1/messages): 300 requests per minute (5 requests/sec burst).
• Media uploads: 30 requests per minute.

Checking Your Rate Limit Status

Every API response returns standard rate-tracking HTTP headers to help you monitor consumption dynamically:

Handling Rate Limit Exceeded Errors (429)

When limits are exceeded, requests return an HTTP 429 Too Many Requests error. The response body is structured as follows:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before retrying.",
    "retry_after_seconds": 15
  }
}

!TIP Always implement a retry logic with an exponential backoff jitter algorithm inside your integration codebase to handle 429 error responses.