Rate limit
Every app, key and workspace has its own allowance: an app stuck in an error loop never slows down the customer's real users.
| Caller | Limit | Counted per |
|---|---|---|
| App token (OAuth) | 600 / minute | app |
| API key | 600 / minute | key |
| A user's MCP connection | 600 / minute | connection |
| Whole workspace (by plan) | Workspace limit by plan | workspace |
| Requests with a token | 6,000 / minute | IP address |
| Requests without a token | 300 / minute | IP address |
| Sign-in, token requests | 10 / minute | IP address |
Workspace limit by plan
All calls of one workspace (users, apps, keys) share one bucket that refills evenly every minute.
| Plan | Limit |
|---|---|
| Trial | 100 / minute |
| Basic / Standard | 300 / minute |
| Professional | 1,500 / minute |
| Enterprise | 10,000 / minute |
Heavy operations
Exports, reports and file imports have their own, tighter limits.
| Limit | |
|---|---|
| Data export | 30 / minute |
| Reports | 20 / hour |
| File import | 5 / hour |
Headers
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The workspace bucket size per minute. |
X-RateLimit-Remaining | Calls left. |
X-RateLimit-Reset | Seconds until the bucket is full again. |
X-RateLimit-Warning | Only below 20%: slow down. |
Retry-After | Only on 429: wait that many seconds, then retry. |
429
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://nextx.vn/errors/rate-limit-exceeded",
"status": 429,
"errorCode": "gateway.rate_limited",
"retryable": true
}On 429, read Retry-After and retry after it; never retry immediately in a loop. Need changes as they happen? Use webhooks instead of polling every few seconds.