---
title: Rate Limits
description: "How rate limiting and usage limits work across the Syntext API."
---

# Rate Limits

Syntext applies two kinds of limits: **request rate limits** (short-window, per-client) and **usage limits** (monthly, per-organization, based on your plan).

## Request Rate Limits

When you exceed a rate limit, the API returns `429`:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait before asking another question.",
    "retryAfterSeconds": 30
  }
}
```

Wait `retryAfterSeconds` before retrying. The [SDKs](/sdks/overview) handle this automatically with exponential backoff.

### AI Assistant Visitor Limits

The public [chat endpoint](/api-reference/chat/ask) is rate-limited **per visitor** to protect your AI query quota from abuse. The limit is configurable per project in the dashboard under **Settings → AI Assistant** (`aiRateLimit`). When a visitor exceeds it, the widget shows a cooldown message.

## Monthly Usage Limits

Plan-based limits are enforced per **organization** and reset monthly:

| Metered resource | Applies to |
|------------------|-----------|
| Builds | [Trigger Build](/api-reference/builds/trigger), git-push builds, PR previews |
| AI queries | AI assistant questions across all your doc sites |

When a limit is reached the API returns `403` with code `USAGE_LIMIT_EXCEEDED`:

```json
{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Monthly AI query limit reached (1000/1000). Upgrade your plan for more AI queries.",
    "current": 1000,
    "limit": 1000
  }
}
```

Current usage is visible in the dashboard under **Organization → Billing**.

## Best Practices

- **Poll builds at ≥5s intervals** — or use build status webhooks instead of polling.
- **Batch content updates** — use the [batch save endpoint](/api-reference/pages/overview) instead of one request per file.
- **Cache `chat/config`** — widget configuration rarely changes.
- **Respect `retryAfterSeconds`** — retrying earlier only extends the cooldown.

<Note>
Analytics beacon endpoints (`/analytics/pageview`, `/analytics/search`, `/analytics/chat`) are designed for high-volume traffic from doc sites and return `202` immediately.
</Note>