Rate limits
Vectros applies three main limits, each tuned for a different purpose:
- A per-tenant business limit at the application layer — a fixed number of requests per minute, selected from your plan. This is the limit you pace against day to day, and the one most of this page is about.
- A per-IP ceiling at the network edge — a high, plan-independent flood-protection limit
of 10,000 requests per five-minute window per source IP. It counts every method, plain
GETreads included, and every client behind one NAT or egress IP shares it. It exists to cut off a single-source flood before it reaches application code. - A batch-write collision budget — an abuse control that
POST /v1/records/batch,POST /v1/scripts/executeand trigger-fired scripts spend, and that the two script paths also check before they run. It is not a request-rate limit, and ordinary batch use never approaches it. See The batch-write collision budget below, which matters because the advice in this page's Handling 429s section — slow down and retry — will not clear it.
The first two are enforced at different layers and return slightly different responses (see
Two layers, two responses below). Two narrower controls can also
answer 429: a per-tenant cap on concurrent script executions (10 by default; the response
carries Retry-After: 2), and an opt-in per-principal burst limit, whose limit is then the
value in X-RateLimit-Limit.
One 429 is not a rate limit at all: on POST /v1/chat, POST /v1/rag and
POST /v1/documents/{id}/ask, a 429 whose body carries errorCode BALANCE_BUSY means your
pre-paid inference balance is momentarily busy with other concurrent requests of yours, so the call
did not start. It is not a shortage (that is a 402) and not a breach of the limits on this page: do
not top up, and retry after the seconds in Retry-After. It carries no X-RateLimit-* headers. See
Handling 429s.
The per-tenant limit
- Window. A fixed one-minute window. Your request count resets at the top of each minute (it is not a rolling window).
- Scope. The limit is per tenant, shared across every key — your live tenant and your test tenant each have their own budget, at the limit your account's plan sets. All of a tenant's API keys and scoped tokens draw from the same per-minute budget — issuing more keys does not raise it.
- What counts. Writes (including deletes), searches,
POST-shaped lookups, and inference count against the limit. PlainGETrequests do not — listing and fetching are not throttled by this limit.POST /v1/scripts/executetakes the write-path limits once, before your script runs, whatever the script itself goes on to do — so a read-only script still spends write-path budget, and there is no free-read allowance on that call. Agent runs count the same way:POST /v1/runsspends one request of the budget when the run starts (the tool calls the run makes are not counted again), and the stored-agent writes (POST,PUTandDELETEon/v1/agents) andPOST /v1/runs/{id}/cancelcount like any other write. Reading an agent or a run withGETdoes not.
Limits by plan
| Plan | Requests per minute |
|---|---|
| Free | 60 |
| Starter | 300 |
| Pro | 600 |
| Scale | 1,200 |
| Enterprise | 1,200 (negotiable) |
An unrecognized or unset plan is treated as Free (60/min). Enterprise agreements can raise the ceiling beyond the Scale default by arrangement.
The batch-write collision budget
POST /v1/records/batch carries one additional limit, and it behaves differently enough from the
other two that retrying the same request will not clear it.
What it counts. Not requests, and not items — only items that collided with a value already
held by a different record: an externalId that belongs to a record outside what your credential
can read, or a value on a field your schema declares unique: true. It is counted per tenant, in
the same one-minute window as the per-tenant limit.
Ordinary batch use spends none of it. That is the design, not a courtesy:
- A clean import — records that do not yet exist — spends zero, however large the batch.
- Re-importing your own records spends zero too, even though every item "collides". Re-sending
a record with an
externalIdyou already own is an idempotent match, not a collision: the existing record is returned to you with statusupdated, which is a success. Blueprint re-applies and repeated syncs are therefore free.
So in practice you only spend this budget by submitting, in bulk, externalIds or unique values
that belong to records you cannot see — which is what the control is for.
If you hit it. The response is 429 with a Retry-After, like the other limits, but the
remedy is different:
- Do not simply back off and retry. The budget is spent on outcomes, not on request rate, so retrying the same batch after a pause spends it again and fails the same way.
- Fix the input instead. Inspect the per-item
resultsfrom your previous batch: every item with statusconflictand error codealready_existsis one that consumed budget. Remove or correct those items and resubmit. - If you are legitimately reconciling against records you cannot read, split the work across windows, or ask support about the right access model for it — needing to probe at volume usually means the credential is scoped more narrowly than the job requires.
Telling it apart from a request-rate 429. Both return 429 with Retry-After, so the status
alone does not distinguish them; the response message does. If you branch on status alone (which is
this page's general advice, and still correct for the other two limits), a collision-budget 429
will look like a burst limit and your backoff will not resolve it — so on POST /v1/records/batch
specifically, read the message before deciding that waiting is the answer.
It is also checked before POST /v1/scripts/execute. When the budget is spent, that call
answers 429 with Retry-After: 60 and a message that the app has spent its uniqueness-probe
budget for the current window; wait for the window to reset.
When you exceed the limit
A request over the limit returns HTTP 429 with a JSON body and a set of headers that tell
you exactly how to recover:
{
"message": "Rate limit exceeded. Please try again later.",
"errorCode": "RATE_LIMITED",
"requestId": "…"
}
| Header | Meaning |
|---|---|
Retry-After | Seconds to wait before retrying. After this many seconds the window resets and the request will succeed (assuming you are within budget again). |
X-RateLimit-Limit | Your tenant's maximum requests per minute: your plan's limit, or the figure agreed for your account if it differs. On a collision-budget 429 from POST /v1/records/batch it is the budget (100) instead. |
X-RateLimit-Remaining | Requests remaining in the current window — always 0 on a 429. |
Retry-After is the value to honor: it is the number of seconds until the current minute window
resets, so a client that sleeps for Retry-After seconds lands in a fresh window with a full
budget.
Handling 429s
- Honor
Retry-After. Sleep for the advertised number of seconds, then retry. This is the single most effective thing a client can do. - Back off exponentially if you retry without reading
Retry-After, and add jitter so a fleet of workers doesn't retry in lockstep. - Pace bulk work. A one-shot backfill (for example, ingesting a large corpus) is exactly the workload that hits this limit. Spread writes across minutes, or cap concurrency so your steady rate stays under your plan's per-minute budget.
- Branch on the
429status, not the message text. The status code is the contract; theerrorCodeand headers are there to help you recover. When you need to tell the causes apart, readerrorCode:RATE_LIMITEDis a request-rate limit,BALANCE_BUSY(inference routes only) is your balance being busy with your own concurrent calls, and neither is cleared by a top-up. ForBALANCE_BUSY, retry afterRetry-After, and consider lowering the concurrency of your inference calls if you see it often.
On POST /v1/runs a 429 has the body { message, errorCode, statusCode } and a Retry-After
header, but no X-RateLimit-* headers, and its Retry-After is a short fixed delay, not the time
until the minute window resets, so a retry can be refused again: keep backing off. Its errorCode
says which limit you reached: RATE_LIMITED for the per-tenant limit above,
PRINCIPAL_BURST_EXCEEDED or PRINCIPAL_QUOTA_EXCEEDED for an opt-in per-principal control,
PROBE_BUDGET_EXHAUSTED for the batch-write collision budget below, CONCURRENT_RUN_CAP or
RUN_HOLD_CAP for too many runs in progress or too much budget reserved by them, and
BALANCE_BUSY as described above. The agents and runs
reference lists them.
The limiter fails open: if the counter store is briefly unavailable, requests are allowed rather than rejected, so a limiter outage never blocks your traffic.
Two layers, two responses
Because the per-tenant limit and the per-IP edge ceiling live at different layers, a 429 can
come from either:
- Application limit (per-tenant, per-minute): the body above, with
Retry-AfterandX-RateLimit-*headers and arequestIdyou can quote to support. - Edge limit (per-IP, flood protection): a
429from the firewall with the sameerrorCode: "RATE_LIMITED"discriminator, but norequestId(the edge has no per-request correlation id). If you contact support about an edge429, quote thex-amz-cf-idresponse header instead.
In both cases the status is 429 and the body carries errorCode: "RATE_LIMITED", so a
single check on the status (and, if you want, the errorCode) handles either layer. The token
exchange is the exception, below.
The token exchange
POST /v1/auth/token/exchange is called before your users have a Vectros credential, usually from
their browser, so it has two limits of its own, and both answer 429 with Retry-After:
- New self-service sign-ups, per issuer registration. When a registration has a self-signup
policy, the exchange creates at most a set number of NEW users through it per minute and per
hour, by your plan. Over the limit it answers in the exchange's OAuth shape:
{"error":"temporarily_unavailable","error_description":"..."}, and no user is created. Existing users and invite sign-ins are never limited this way. The account owner can read the limits, and raise or lower them up to the plan's maximum, with the developer portal API (GET/PATCH /developer/self-signup-limits). Plan a large SSO roll-out against the hour limit. - Requests per IP: 300 exchange requests per five minutes per source IP, at the edge, in the
edge's
errorCode: "RATE_LIMITED"shape (not the OAuth shape). Every user behind one NAT or office egress IP shares it.
Notes & limits
- The per-minute window is fixed, not rolling: bursting right before a minute boundary and again right after briefly allows up to two windows' worth of requests in a short span. Pace to your average rate, not the instantaneous one.
- Plain
GETreads are not counted by the per-tenant limit today. Plan your read-heavy workloads against the edge per-IP ceiling (10,000 requests per five minutes per source IP), not this limit. - The limit is selected from your plan. A plan change reaches your API keys within a few minutes: propagation is asynchronous and authorizer decisions are cached for up to 5 minutes. A scoped token carries the limit it was minted with until it expires (up to one hour), so a token minted before the change keeps its old limit until you re-mint it or it expires. The same holds for the opt-in per-principal controls (burst limit and usage quota): a scoped token you mint for an end user is limited per principal only if your account was opted in when it was minted, and an opt-in or opt-out reaches existing scoped tokens when they are re-minted or expire.