Limits and errors
Error codes, rate limits and plan limits.
Errors
Every error has the same shape. Match on code, not on the message, which is written for people and may change. Every response, error or not, carries an x-request-id header to quote when reporting a problem.
{
"error": {
"code": "invalid_request",
"message": "`ttl_seconds` must be between 10 and 604800"
}
}- 400 bad_signature
- A billing webhook call whose signature does not check out. Only Stripe sees this.
- 401 unauthorized
- The key or sign-in is missing, wrong, revoked or expired.
- 402 plan_limit
- The workspace's plan has no requests left this month, it reached the monthly request cap it pays per request under, there is no room for another active key or person, or the feature requires a higher plan.
- 403 forbidden
- The caller may not do this, such as an agent key on a person's route, or a member writing a rule.
- 403 action_out_of_scope
- The agent key may not ask for this action. Nothing was stored. Retrying will not help.
- 403 not_assigned
- A rule sent this request to other people, and it has not escalated. The message names them.
- 404 not_found
- No such thing, or it belongs to another workspace. The two look the same on purpose. An agent key also gets it for a request another key made.
- 409 already_decided
- The request was decided or withdrawn already. Decisions are final.
- 409 expired
- The request expired before a decision.
- 409 already_approved
- You approved this already; it needs a different person.
- 409 changes_differ
- Another person approved it with different changes. Approve the same changes, or deny it.
- 409 not_approved
- An outcome was reported for a request that was not approved.
- 409 outcome_already_reported
- The request already has an outcome. It is reported once.
- 409 last_owner
- A workspace must keep at least one owner.
- 409 sole_owner
- You are the only owner of a workspace others are in, so your account cannot be deleted yet. The message names the workspace.
- 409 changed
- Your workspaces changed while your account was being deleted. Nothing was deleted; try again.
- 409 account_deletion_unavailable
- This server cannot delete accounts. Write to whoever runs it.
- 409 already_member
- The person is already in the workspace.
- 409 billing_disabled
- Plans cannot be bought on this server. Contact us for a paid plan.
- 409 already_subscribed
- The workspace already pays for a plan. Change it under Manage billing.
- 409 no_billing_account
- The workspace has not paid for a plan yet, so there is no billing portal.
- 409 endpoint_disabled
- The webhook is turned off. Turn it on before sending a test.
- 409 push_disabled
- Push notifications are not set up on this server, so a browser cannot subscribe.
- 422 invalid_request
- A field is missing, malformed or out of range. The message says which.
- 422 not_confirmed
- Deleting a workspace or an account needs its exact name or email address.
- 429 rate_limited
- The key called too often, or one address sent too many Enterprise inquiries. Retry-After says how many seconds to wait.
- 500 internal
- Something failed on our side. Quote the x-request-id when reporting it.
- 502 billing_unavailable
- Stripe could not end the workspace's plan, so nothing was deleted. Try again in a few minutes.
- 502 sign_in_unavailable
- The sign-in service could not be reached, so nothing was deleted. Try again in a few minutes.
- 502 sign_in_not_deleted
- Your workspaces and settings were deleted, but your sign-in was not. Try again, and write to support if it keeps failing.
A 500 never says what went wrong; the cause is logged on the server under the request id. Over MCP, a refusal such as an unknown request comes back as a tool result marked as an error, with the same message; see MCP server.
Handling them in an agent
Every error means the same thing for the action: it does not happen. Only the reason differs, and with it what to do next.
import { ApprovalApiError, NotApprovedError } from "@variantgate/agent/errors";
try {
await approvals.guard(request, act);
} catch (error) {
if (error instanceof NotApprovedError) {
// Denied, expired, withdrawn, paused or approved only with changes. Stop.
} else if (error instanceof ApprovalApiError && error.code === "rate_limited") {
// Too many calls from this key. Back off and ask again later.
} else {
// "network" (status 0), a 5xx, or anything else: do not act.
throw error;
}
}In Python the same classes exist, and both are a VariantGateError; ApprovalApiError has code and status. The variantgate command exits 2 on an error and never runs its command.
How often an agent may call
- One agent key may make 600 calls a minute.
- A call that waits with
wait_secondscounts once, however long it waits. Checking one request once a second is well inside the limit. - Past the limit the answer is 429 with a
Retry-Afterheader, in seconds, until that key’s minute is over. MCP calls count the same. - A call is counted only once the key is known to be real, so guessing keys cannot use up a real key’s minute. People are not limited this way.
HTTP/1.1 429 Too Many Requests
retry-after: 12
x-request-id: 0190d1c5-7f3a-7c2e-9b1d-2f4e8a6b1c3d
{
"error": {
"code": "rate_limited",
"message": "too many calls with this key; try again in 12 seconds"
}
}What each plan includes
- Every plan
- Approve in the inbox, email, push, Slack, Teams or Discord; the weekly summary email; try the rules; pause workspaces; pause and scope keys; view and verify the sealed record, activity log and insights.
- Free · €0
- 100 requests a month, 2 agents, 1 person. No rules.
- Pro · €9/month
- Unlimited requests, 50 agents, 1 person. Standing rules with amount limits and budgets; remember decisions; edit before approving; signed webhooks to your own systems.
- Team · €15/person/month or per request
- Everything in Pro; any number of owners and members; invitations and two-person approval.
- Business · €39/person/month or per request
- Everything in Team; routing, escalation, reports per agent and sealed audit exports.
- Enterprise · talk to us
- Everything in Business; SAML, self-hosting, invoice billing and a data processing agreement, priority support. Agreed by contract.
After a downgrade, nothing is deleted. Existing rules, budgets, routes and two-person approval keep applying because ignoring an owner's rule could weaken a denial, and existing webhooks keep being sent to. New writes need the appropriate plan. Removing rules, members, invitations and webhooks is always allowed.
Per request: Team costs €0.05 each, at least €15 in a month with requests (the first 300 covered); Business costs €0.12 each, at least €39 (the first 325 covered). A month with no requests costs €0.
- Free
- 100 requests a month and 2 active agent keys.
- Paid plans
- No limit on requests, and up to 50 active agent keys.
- Paid per request
- Team and Business paid per request take up to their monthly request cap: 10,000 unless an owner sets it, from 100 to 1,000,000, in Settings.
Settings shows the plan and how much of it is used this month. Months are counted in UTC. A request or a key past the plan’s limit gets 402 plan_limit. Revoking a key frees its place.
A workspace that pays per request counts every request its agents make, including the ones a rule answers. Past its monthly cap, a new request gets 402 plan_limit and nothing is stored or billed, so the agent must not act. The cap protects your money, so it holds even on a server that does not enforce plan limits, and agents asking at the same moment are counted one at a time, so none gets past it.
On a self-hosted server, usage is always counted but limits are refused only when API_ENFORCE_PLAN_LIMITS=true, and the rate limit is the API’s API_AGENT_CALLS_PER_MINUTE setting. Each instance counts calls on its own, so with several instances a key gets up to that many times the limit. See Self-hosting.
Sizes
- Request body
- At most 64 KB.
- agent, action
- 1 to 200 characters each.
- summary
- At most 2,000 characters.
- details
- A JSON object, within the body's 64 KB.
- amount
- At most 4 decimals and at most one trillion, with a three-letter currency.
- ttl_seconds
- 10 seconds to 7 days. Default 15 minutes.
- wait_seconds
- 0 to 30.
- Notes
- A decision or outcome note: at most 2,000 characters.
- Rules
- At most 100 in a workspace.
- A rule's people
- 1 to 10 named deciders, escalating after 60 seconds to 1 day; 1 to 3 approvals.
- Agent keys
- At most 50 active in any workspace; names up to 100 characters.
- Workspaces
- At most 20 per person; names up to 100 characters.
- Invitations
- At most 50 open at once; each works once, for 7 days.
- Webhooks
- At most 5 per workspace; the last 50 deliveries of each are kept.
- Record search
- At most 200 characters; up to 200 requests a page.
- CSV export
- The 10,000 most recent rows. The x-record-complete header is false when older ones were left out.
What each field of a request means is on Requests; what a rule may say is on Rules; every endpoint is in the API reference.