Rate Limits

API requests are rate-limited per plan to ensure fair usage. Monitor the response headers to stay within limits and implement retries when needed.

Per-Tier Limits

Limits are enforced as requests per minute (RPM). The counter resets every 60 seconds.

Plan	Requests per minute
Plus	`60`
Pro	`120`
Enterprise	`300`

Response Headers

Every API response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute for your plan
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (ms) when the limit resets
`Retry-After`	Seconds to wait before retrying (present only on 429 responses)

Handling Rate Limits

Read the headers to track your usage and implement exponential backoff when you receive a 429 response.

javascript

async function chatWithRetry(agentId, message, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(`https://chatspark.io/api/v1/agents/${agentId}/chat`, {
      method: "POST",
      headers: {
        "Authorization": "Bearer cs_live_...",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ message }),
    });

    // Read rate limit headers
    const limit = res.headers.get("X-RateLimit-Limit");
    const remaining = res.headers.get("X-RateLimit-Remaining");
    const reset = res.headers.get("X-RateLimit-Reset");
    console.log(`Rate limit: ${remaining}/${limit}, resets at ${reset}`);

    if (res.ok) return res.json();

    if (res.status === 429) {
      const retryAfter = res.headers.get("Retry-After") || 60;
      const delay = parseInt(retryAfter, 10) * 1000;
      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    throw new Error(`Request failed: ${res.status}`);
  }
  throw new Error("Max retries exceeded");
}

Authentication

Errors