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_seconds counts 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-After header, 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.