Rate limits

Chatevo applies rate limits per organization, deployment, and endpoint class to keep the platform stable for all tenants.

Limit categories

Category	Scope	Default limit (Production)	Window
Global	Organization API key / session	1,000 requests	1 minute
Auth	Login, token refresh, password reset	10 attempts	1 minute per IP
Chat	Direct API messages	60 messages	1 minute per deployment
Widget	Config + message endpoints	120 requests	1 minute per deployment
Webhook	Outbound delivery attempts	100 deliveries	1 minute per endpoint

Higher limits are available on Pro and Enterprise plans. Contact sales for custom quotas.

Response headers

Every rate-limited response includes:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on `429` responses)

Example 429 body:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Chat rate limit exceeded for deployment dep_abc123.",
    "retry_after": 8
  }
}

The widget embed script and config endpoint are optimized for fast first paint:

Metric	Target
`chat.js` download + parse	≤ 500 ms (CDN, gzip)
Config fetch (`/api/v1/widget/config`)	≤ 300 ms p95
Total time to interactive bubble	≤ 2 seconds on a typical 4G connection

If your site exceeds this budget due to heavy third-party scripts, defer non-critical JS or load the Chatevo script with async before </body>.

Per-category details

Global (REST management)

Applies to assistants, knowledge bases, tools, conversations, and webhook registration. Bulk automation should batch writes and respect Retry-After.

Auth

Protects against credential stuffing. Repeated 401 responses do not bypass this limit — use exponential backoff.

Chat (Direct API)

Counts user and assistant messages sent via /api/v1/messages. Streaming connections count as one message per request.

Counts config loads and message posts from the embed. Each visitor session typically uses 1 config request plus message requests during the conversation.

Webhook (outbound)

Chatevo retries failed deliveries with backoff. Your endpoint should respond within 5 seconds with 2xx. See Webhook HMAC.

Best practices

Cache assistant and KB metadata server-side; do not poll list endpoints in a loop.
Use webhooks for conversation events instead of polling conversations.
On 429, wait at least Retry-After seconds before retrying.
Load-test staging deployments before high-traffic launches.