AACSearch / guide
Limits and quotas
The monthly request quota per plan and what counts against it, rate limits per key scope, the per-session AI allowance, and request size limits.
Three independent mechanisms can answer 429: the organization's monthly
quota, rate limits on keys, and a search key's per-session AI
allowance. AI operations are also paid for in credits (402 when the wallet
is empty); that is covered under credits.
How to handle each answer is covered under errors and retries.
Monthly request quota
| Plan | Requests / month |
|---|---|
| Free (no subscription) | 3,000 |
| Starter | 5,000 |
| Pro | 50,000 |
What counts. Each operation forwarded to the search engine counts one
request, but only when the engine answers successfully (2xx). This covers
searches, multi-search, document reads and writes, imports and collection
changes. Operations the control plane runs itself count one request when they
do billable work, such as query suggestions and assistant turns. Failed
requests count nothing. The console's Usage screen breaks the count down into
search, indexing, AI and other.
The period. With a subscription, the quota resets when the subscription period renews. Without one, it resets at the start of each calendar month. Owners get an email at 80% and at 100% of the quota.
When it is used up, every operation answers 429 until the reset:
{
"message": "Quota exceeded for this organization - 5000 requests this period; resets at 2026-10-01T00:00:00.000Z.",
"resets_at": 1790812800000
}Retry-After holds the seconds left until the reset. getEntitlement and the
health operation keep answering, so a client can find out why and when.
Rate limits
| Limit | Applies to | Counted per | Ceiling | Answer |
|---|---|---|---|---|
| Visitor | Search keys, on operations forwarded to the engine | Key and client IP | 100 requests per 10 seconds, on every plan | 429, Retry-After: 10 |
| Key ceiling | Search keys, on operations forwarded to the engine | Key | Free 180, Starter 300, Pro 3,000 requests per minute | 429, Retry-After: 60 |
| Key restriction | Any key that has a per-minute limit set in the console | Key (sliding minute) | The value you set | 429, Retry-After in seconds |
| AI allowance | Search keys, on AI operations | X-NOVA-SESSION-ID | 20 AI operations per minute | 429, data.retry_after in seconds |
A search key ships inside a browser, so it has two throttles:
- Visitor limit. Keeps one shopper's autocomplete traffic from using up the whole storefront's budget.
- Key ceiling. Still stops a copied key that is used from many IPs.
Full keys belong on your server and skip both of these. They are held only to the monthly quota and to a per-key limit if you set one.
The visitor and key-ceiling answers have a message starting with Forbidden -,
but their status is 429. Handle them by status.
A shared office or mobile-carrier NAT puts many shoppers behind one IP, and they then share one visitor limit. If a storefront hits the visitor limit during normal traffic, give each visitor a short-lived browser key (see the widget's keys) instead of one shared search key.
Request size limits
| What | Limit | Over the limit |
|---|---|---|
Events per ingestEvents batch | 1–500 | 400 |
Image for uploadMedia and image search | 8 MB | 400 |
| Audio for transcription and voice search | 25 MB | 400 |
Raw image body for putMediaContent | 100 MB, Content-Length required | 413 (411 without length) |
YML feed file for uploadIngestFeed | 500 MB, Content-Length required | 413 (411 without length) |
The hosting platform's own request-body limit applies before these, so a large
feed file can be refused earlier. Give large feeds to createIngestJob by
url instead of uploading them.
SCIM provisioning
Synchronize organization membership from an identity provider: connect it with a SCIM token, understand what Users and Groups cover, and rotate or revoke tokens safely.
Errors and retries
The JSON error body, every status code the tenant API answers with, which failures are worth retrying, and how Idempotency-Key protects a retried write.