Errors

One envelope#

Every failure on the REST API and on 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.

{
  "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.

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.

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#

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

Every 401 carries WWW-Authenticate: Bearer realm="compass".

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.

There are no rate limits#

Veriticity publishes no rate limits on the REST API, the OAuth endpoints or MCP today. There is no 429 in the error vocabulary and no Retry-After header anywhere.

This is stated plainly because the opposite is easy to assume. Do not write handling for a response that does not exist. If limits are introduced they will be documented here first, with notice.

Reasonable client behaviour still applies: back off on internal_error, and send an Idempotency-Key on purchases so a retry cannot double-spend. See Purchases.