Copy page

Resources

Rate Limits

Neuratel applies rate limits to protect platform stability and ensure fair usage. This page covers the limits, how to detect them, and how to build resilient integrations.

Default Rate Limits

Scope	Limit	Window
Per IP address (unauthenticated)	20 requests	1 minute
Per API key (authenticated)	100 requests	1 minute
Bulk contact import	10 imports	1 hour
Knowledge base file upload	10 uploads	1 hour

Authenticated requests receive significantly higher limits than unauthenticated ones. Always include your API key.

Enterprise accounts can request higher limits. Contact [email protected].

Rate Limit Headers

Every response includes rate limit headers:

Code
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1712505660

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

429 Response

When you exceed the limit, the API returns HTTP 429:

Code
{
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMIT_5001",
    "message": "Too many requests. Retry after 23 seconds.",
    "request_id": "req_abc123"
  }
}

The response also includes a Retry-After header with the number of seconds to wait:

Code
Retry-After: 23

Handling Rate Limits

Exponential Backoff

The recommended approach for handling 429 responses:

Code
import httpx
import time

def request_with_backoff(client: httpx.Client, method: str, url: str, **kwargs):
    max_retries = 5
    base_delay = 1  # seconds

    for attempt in range(max_retries):
        response = client.request(method, url, **kwargs)

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get("Retry-After", base_delay * (2 ** attempt)))
        time.sleep(retry_after)

    raise Exception("Rate limit exceeded after max retries")

Code
async function requestWithBackoff(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    const retryAfter = parseInt(response.headers.get("Retry-After") || (2 ** attempt));
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error("Rate limit exceeded after max retries");
}

Proactive Throttling

Check remaining quota before sending requests to avoid hitting limits:

Code
remaining = int(response.headers.get("X-RateLimit-Remaining", 100))
if remaining < 5:
    reset_at = int(response.headers.get("X-RateLimit-Reset", 0))
    wait = max(0, reset_at - time.time())
    time.sleep(wait)

Code
const remaining = parseInt(response.headers.get("X-RateLimit-Remaining") || "100");
if (remaining < 5) {
  const resetAt = parseInt(response.headers.get("X-RateLimit-Reset") || "0");
  const waitMs = Math.max(0, resetAt * 1000 - Date.now());
  await new Promise((resolve) => setTimeout(resolve, waitMs));
}

Bulk Operation Limits

Some endpoints have separate limits to prevent resource exhaustion:

Operation	Limit	Notes
Contact CSV import	10,000 contacts per file	Max 10 MB file size
Knowledge base upload	21 MB per file	PDF, DOCX, TXT supported
Batch imports per hour	10	Applies to both contacts and knowledge base
Webhook test sends	10 per minute	Per webhook endpoint

Best Practices

Cache Read-Heavy Responses

For data that changes infrequently (agent configs, number lists), cache responses locally and refresh on a schedule rather than re-fetching on every request.

Code
from functools import lru_cache
from datetime import datetime, timedelta

_agents_cache = None
_agents_cache_time = None

def get_agents(client: httpx.Client):
    global _agents_cache, _agents_cache_time
    if _agents_cache and _agents_cache_time and datetime.now() - _agents_cache_time < timedelta(minutes=5):
        return _agents_cache
    response = client.get("/v1/agents")
    _agents_cache = response.json()
    _agents_cache_time = datetime.now()
    return _agents_cache

Batch Where Possible

Use bulk endpoints instead of individual requests. For example, upload one CSV with 5,000 contacts instead of making 5,000 individual contact creation requests.

Distribute Requests

If you have multiple services calling the API, use a separate API key per service. Rate limits are tracked per key, giving each service its own quota.

Monitor Usage

Log X-RateLimit-Remaining values to detect when your integration is approaching limits:

Code
import logging

logger = logging.getLogger("neuratel")

response = client.get("/v1/agents")
remaining = response.headers.get("X-RateLimit-Remaining")
logger.info(f"Rate limit remaining: {remaining}")

if int(remaining) < 10:
    logger.warning("Approaching rate limit")

Next Steps

• Error Codes — handle RATE_LIMIT_5001 and other errors
• Using API Keys — create per-service keys for separate rate limit pools
• Production Checklist — verify your integration handles rate limits