Errors

One envelope#

Every failure on the REST API, and every HTTP-level refusal at /mcp, uses the same shape. code is stable and safe to branch on. message is written for a person and may be reworded without notice — do not match on it. A tool that refuses inside a successful MCP call answers differently; see MCP.

{
  "error": {
    "code": "invalid_request",
    "message": "The purchase request is not valid.",
    "issues": [
      {
        "path": "amountMinor",
        "code": "AMOUNT_NOT_POSITIVE",
        "message": "amountMinor must be greater than zero. Veriticity evaluates purchases, not refunds."
      },
      {
        "path": "agentId",
        "code": "UNKNOWN_FIELD",
        "message": "agentId is not accepted here. The agent is determined by the API key, never by the request body."
      }
    ]
  }
}

The OAuth endpoints are the one exception: /oauth/token and /oauth/revoke answer RFC 6749’s {error, error_description}, because that is what every OAuth library in the world parses.

Every response from /v1 and /mcp, success or failure, carries an X-Request-Id header. It is the id Veriticity recorded the request under. Log it, and include it when you contact Veriticity support. The SDK puts it on every error as requestId.

Validation issues#

issues[] appears on invalid_request and draft_invalid only, and it always carries every problem found rather than the first — so four mistakes are fixed in one round trip instead of four. A purchase request lists at most 100; when there are more, the last entry has the code TOO_MANY_ISSUES and says how many were left out.

Unknown fields are refused rather than ignored, with guidance saying where authority actually comes from. A body containing agentId is a caller who believes they are choosing the agent, and silently dropping it would leave them believing it.

type ApiError = {
  error: {
    code: string;
    message: string;
    issues?: { path: string; code: string; message: string }[];
  };
};

// These three mean "stop". Retrying, refreshing or re-authorising changes
// nothing, and a client that loops on them will loop forever.
const PERMANENT = new Set([
  "api_key_not_permitted",
  "oauth_not_permitted",
  "connection_unauthorized",
]);

if (!response.ok) {
  const { error } = (await response.json()) as ApiError;

  if (PERMANENT.has(error.code)) {
    await alertAnOperator(error);
    return;
  }

  if (error.code === "insufficient_scope") {
    // This one *is* fixable by asking for more.
    return reauthorize();
  }

  if (error.code === "invalid_request") {
    // Every problem at once, so four fields are fixed in one round trip.
    for (const issue of error.issues ?? []) {
      log(`${issue.path}: ${issue.message}`);
    }
  }

  throw new Error(`${error.code}: ${error.message}`);
}

Every error code#

38 codes. This table is generated from the same table the API answers from, so it cannot fall behind.

Every 401 from /v1 carries WWW-Authenticate: Bearer realm="compass". A 401 from /mcp carries Bearer realm="veriticity" with a resource_metadata pointer to where to authenticate.

Refusals you must not retry#

Three codes mean “stop”, and a client that treats them as transient will retry forever. They are kept distinct precisely so you can tell them apart.

Contrast insufficient_scope, which is fixable: re-authorise with the scope named in the message. That distinction is why these are four codes and not one.

Plan limits#

Each plan includes a number of purchase requests per billing period, limits on how many agents, members, policies, API keys, connected apps and webhook endpoints an organisation may have, and a set of features. A purchase request counts once, however it was submitted and whatever the decision. Simulations, reads, approvals and other API calls never count, and nothing in Sandbox counts or is limited by a plan.

An owner chooses and changes the plan in the Live dashboard. The API cannot change it. See the Veriticity pricing page for current plans, limits, features and pricing.

When a plan limit is reached, the answer is 402 (or 409 resource_limit_reached when creating something) with a details object naming the limit. Nothing was done, and waiting a few seconds will not help: plan limits are not rate limits.

{
  "error": {
    "code": "purchase_allowance_exhausted",
    "message": "This organisation has used all the purchase requests its plan includes this month (1000 used, 1000 included). New purchase requests are refused until the allowance resets, unless an owner upgrades the plan in the dashboard, under Settings > Plan & usage.",
    "details": {
      "limit": "purchase_requests",
      "used": "1000",
      "included": "1000",
      "periodEnd": "2026-10-10T00:00:00.000Z"
    }
  }
}

Rate limits#

Every REST operation is limited per credential — one API key, or one OAuth connection whichever token it presents. Purchase submission is also limited per organisation, and webhook tests per endpoint and per organisation. Live and Sandbox count separately and apply the same limits.

Each limit is a fixed window that starts with the first request and lasts for its stated length. Every request counts, including refused ones, but a refused request never extends the window.

Every response to a request that passed authentication carries three headers describing the tightest limit that applied:

Over a limit, the answer is 429 rate_limited with Retry-After in whole seconds. Nothing was done: a refused purchase was not evaluated and reserved no budget. Waiting that long and sending the same request again will work.

The headers are occasionally absent from a successful response. That means the limit could not be measured for that request, and it was let through; do not treat a missing header as an unlimited allowance.

Purchase submission, outcome reports and webhook tests are never let through unmeasured. When the limit cannot be checked they answer 503 temporarily_unavailable with Retry-After, and nothing was done. Retry a purchase with the same Idempotency-Key, and an outcome with the same reportId. See Purchases.

/oauth/token is limited per client address and answers 429 with Retry-After and an OAuth error body. Over MCP, request_purchase shares the purchase submission limits and refuses with the tool error rate_limited.

The SDK does not retry or wait on a 429. It surfaces as a RateLimitError with code rate_limited and status 429, carrying retryAfterSeconds and the quota it was refused by. See SDK.

Retrying safely#

A limit is counted before the request is read and before the Trust Engine runs, so a 429 and a 503 temporarily_unavailable both mean nothing was submitted. Sending the same request again creates no second decision.

A timed-out or dropped request is a different case, and the difference matters on purchase submission: the request may have been received and processed while the response was lost. Retry that only with the same Idempotency-Key.