Rate limits

Vectros applies three main limits, each tuned for a different purpose:

  1. 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.
  2. 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 GET reads 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.
  3. A batch-write collision budget — an abuse control that POST /v1/records/batch, POST /v1/scripts/execute and 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. Plain GET requests do not — listing and fetching are not throttled by this limit. POST /v1/scripts/execute takes 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/runs spends 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, PUT and DELETE on /v1/agents) and POST /v1/runs/{id}/cancel count like any other write. Reading an agent or a run with GET does not.

Limits by plan

PlanRequests per minute
Free60
Starter300
Pro600
Scale1,200
Enterprise1,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 externalId you already own is an idempotent match, not a collision: the existing record is returned to you with status updated, 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 results from your previous batch: every item with status conflict and error code already_exists is 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": "…"
}
HeaderMeaning
Retry-AfterSeconds to wait before retrying. After this many seconds the window resets and the request will succeed (assuming you are within budget again).
X-RateLimit-LimitYour 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-RemainingRequests 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 429 status, not the message text. The status code is the contract; the errorCode and headers are there to help you recover. When you need to tell the causes apart, read errorCode: RATE_LIMITED is 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. For BALANCE_BUSY, retry after Retry-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-After and X-RateLimit-* headers and a requestId you can quote to support.
  • Edge limit (per-IP, flood protection): a 429 from the firewall with the same errorCode: "RATE_LIMITED" discriminator, but no requestId (the edge has no per-request correlation id). If you contact support about an edge 429, quote the x-amz-cf-id response 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 GET reads 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.