Errors

Probarion reports a problem in one of these layers, and each layer has its own codes:

• The vault contract refuses a call with a panic whose message is exactly PROBARION:<Code>. The whole call reverts.
• The SDK throws errors that extend ProbarionError and carry .code. What the vault or the node answered about a spend comes back in the outcome's code instead.
• The hosted app's HTTP routes answer with an HTTP status and a JSON body, { error, detail? }.

Every vault code and SDK error class has its own anchor, so you can link it, for example /docs/build/errors#NoMandate. Each HTTP row is anchored by its status and code, for example /docs/build/errors#http-404-not_found. The transaction failure codes and the unknown outcome codes are linked through their sections' anchors, Transaction failures and Unknown outcomes. SDK rule ids such as mandate.over_per_payment are not errors. They are the reasons a decision gives, and they are on Spend outcomes.

Where a code shows up#

The contract builds every refusal message in one place:

    pub fn message(self) -> String {
        format!("PROBARION:{}", self.as_str())
    }

On NEAR, a panic undoes every state change the call made. The failed transaction stays on chain, and the code reaches you in one of these forms:

The README's evaluation records this checkSpend() answer for 6 USDC on a mandate that allows at most 5 USDC per payment:

6 USDC: { ok: false, code: 'OverPerPayment', would_hold: false }

Read a code in your own code#

The SDK exports these helpers for vault codes and for the out-of-NEAR codes:

• extractProbarionCode(value) reads the first PROBARION:<Code> in a string, an error or a nested RPC failure. It returns the bare code when it is a vault code, else null, even when a vault code comes later.
• isVaultErrorCode(code) is true only for a code in VAULT_ERROR_CODES.
• normalizeVaultCode(code) strips a PROBARION: prefix and checks nothing else, so test its result with isVaultErrorCode.
• isOutOfNearCode(code) is true for LackBalanceForState and NotEnoughBalance.

import {
  extractProbarionCode,
  isOutOfNearCode,
  isVaultErrorCode,
  normalizeVaultCode,
} from "./packages/sdk/dist/index.js";

console.log(extractProbarionCode("Smart contract panicked: PROBARION:NoMandate")); // NoMandate
console.log(extractProbarionCode("PROBARION:PayeeMismatch")); // null: not a vault code
console.log(normalizeVaultCode("PROBARION:Frozen")); // Frozen
console.log(isVaultErrorCode("LackBalanceForState")); // false
console.log(isOutOfNearCode("LackBalanceForState")); // true

The comments give what packages/sdk/src/errors.ts and packages/sdk/src/tx.ts return for these inputs. Save the file in the root of a clone built as Install shows, and run node codes.mjs there.

The CLI#

check asks the vault's free check_spend view and prints its answer on the first line. A refusal looks like this, and the command exits 1:

REFUSED: PROBARION:OverPerPayment

Any other failure of the CLI prints error: <message> on stderr and exits 1. check and verify exit 64 for a usage error, so a bad flag never looks like a refusal or a failed check.

The CLI signs no owner or approver call. It checks the input, writes the arguments to a file and prints the near-cli-rs command. When the vault refuses that call, near-cli-rs shows Smart contract panicked: PROBARION:<Code>.

Vault error codes#

The table lists every code in VAULT_ERROR_CODES (packages/core/src/types.ts), in the contract's own order. The factory contract writes its refusals in the same format, with the same names.

• Raised by names the methods that refuse with the code. "check n" is the n-th of the 14 spend checks that spend and check_spend run, in the order on How a payment is checked. When two checks would fail, the first one is the answer.
• Retry helps is Yes when the same call, sent again unchanged after a wait, is expected to pass. No means something has to change first, such as the request, the signer or a mandate.

With process(), many of these codes never reach the vault. The SDK's decide() mirrors most spend checks and refuses first, as refused_by_code with a rule id. Then process() asks check_spend before it sends anything. Spend outcomes lists the seven statuses process() returns. The order, the limits and the counters behind each check are on How a payment is checked and Mandates.

When the vault answers DuplicateRef or DuplicateInvoice#

A ref is used up once the vault accepts a spend, held or paid, and it stays used even if the payout fails. A refused spend reverts every change, so its ref stays free. An invoice_hash is taken only while a spend on it is held, pending, paid or burned.

process() refuses a used ref and a taken invoice by code first, with invoice.duplicate, so the vault answers DuplicateRef or DuplicateInvoice only when a spend with that ref or invoice landed after the SDK read the vault.

When the check_spend dry run answers the duplicate code, process() returns refused_by_contract with that code and txHash null at once, because nothing of this cycle was sent. When spend itself answers it, the spend that holds the ref or the invoice can be this cycle's own first copy, whose answer was lost. So for that answer the SDK does not report the code at once. It lists the vault's spends and looks for this decision's own spend, with the same ref, decision hash, invoice, mandate and amount:

A spend that may have paid is never reported as refused or failed. To look a spend up yourself, read the vault's spend list: spends.get takes a spend id, not a ref, and the contract has no lookup by ref. Let an agent pay shows the lookup.

SDK errors#

Every error class the SDK exports extends ProbarionError, so one instanceof ProbarionError catches them all, and .code names the case. A subclass can share its parent's .code, so test the class with instanceof when the difference matters.

Thrown or returned#

process() returns an outcome, not an error, for everything the vault or the node answers about the spend: a refusal, a failed transaction and an unknown outcome are statuses. It throws when something is wrong before a spend can be sent:

• ConfigError: the instance has no agent key or no ledger key, the agent key does not sign as the vault account, or the ledger key is not the vault's. It is also thrown when the agent's sender refuses the call as not set up: the decision entry is then written, and nothing is sent. The constructor throws it too for a model with no API key. Pass model: null to decide by code only.
• ProbarionError with the code InvalidInput: an input it cannot use, for example a facts.invoice_hash that is not hashInvoice(text), or a facts.po_ref that is neither null nor a verbatim part of the text. Nothing is written.
• RpcError or ViewError: a read of the vault failed.
• LedgerConflictError: another writer moved the ledger since this decision was made. No entry was written and no spend was sent, and the SDK never retries it by itself.
• LedgerError: the ledger store failed.
• ProbarionError with the code Internal: a failed internal consistency check, which you should report. Nothing is written and nothing is sent.

Once spend is sent, process() does not throw: every answer becomes an outcome. That is inferred: it follows from the code, and no test shows it yet. These failures are not thrown at all:

• A model step that fails is logged, and the cycle decides with the rules only.
• A failed anchor is logged, and the outcome's anchorTxHash is null. The next cycle anchors the whole tail.
• A payment entry that could not be written leaves the outcome as it is, with ledgerComplete: false.

Called directly, VaultClient.spend() throws where process() returns an outcome: a TxRejectedError when the node refused the signed transaction for any reason except the vault's NEAR balance, a ProbarionError with the code TxSendFailed when nothing was sent, and a TxOutcomeUnknownError when the outcome is not known. A vault refusal, and a node refusal for LackBalanceForState or NotEnoughBalance, come back as a value, with ok: false and the code.

Transaction failures#

These codes are not vault codes. process() returns them in the outcome's code, with the status failed, when the spend did not run or its own receipt failed:

The node refusals are the kinds of a TxRejectedError. In every row spendId is null: the vault did not accept the spend. For TxSendFailed and a node refusal nothing ran at all, so the ref is still free. For the out-of-NEAR codes and TxFailed, the chain refused the call or the spend's own receipt failed, and a failed receipt reverts like a refusal, so the ref stays free there too. That is inferred: it follows from the code, and no test shows it yet.

How a missing agent key shows up is inferred too. The SDK reads the key from the vault account before it signs, so a key the account does not have fails there, as TxSendFailed, and AccessKeyNotFound needs the key to go away after that read. With process(), a key the vault does not list never gets that far: it is refused by code when no mandate names it, and else the check_spend dry run answers NotAgent. The missing key process() can meet is one the vault still lists, for example after its key-adding receipt failed.

A failed outcome can also carry a spend status as its code, with spendId set. Then the vault accepted the spend and released it: the payout failed, or the spend the SDK found by ref was rejected or expired. Its ref is used up, so the same invoice needs a new ref.

Unknown outcomes#

These codes come with the status unconfirmed. The spend was sent, or may have been, and may have paid:

HTTP API errors#

The hosted app's routes answer an error with a JSON body that is never cached:

• the headers content-type: application/json; charset=utf-8 and cache-control: no-store;
• the body { "error": "<code>" }, with a "detail" string when the route has more to say. A few rows add fields, which the table names.

For example, a request the rate limiter refuses gets this body:

{ "error": "rate_limited", "detail": "Try again in 12 s" }

A 429 from the shared rate limiter also sends a Retry-After header with the same number of seconds as its detail, Try again in N s. The faucet's daily limits answer 429 with a sentence of their own instead, and a Retry-After that runs to midnight UTC.

Who calls these routes#

The routes belong to the hosted app: its console, sign-in, top-up and proof files, among others. They are not an agent API.

• The console routes need a signed-in wallet session.
• The sign-in, sign-out, console, top-up and Canary routes that a page posts to check that the request comes from a page at the same address, and answer 403 bad_origin otherwise. The alert links' confirm and stop routes do not check it: the code or token from the alert email is the credential.
• In the console routes, a vault that does not exist gets the same 403 forbidden as one you are not a member of, so a route never confirms a vault id. The faucet answers 404 not_found instead, for these, for a member who is not the owner and for a vault registered on the other network.

An agent pays from its own process, through the SDK. The CLI sends no spend: check only dry-runs one. See Let an agent pay.

On a testnet vault, test USDC comes from the faucet. Signed in as the vault's owner, open its Top-up tab (/console/<vault>/topup) and press the "Add test USDC" button. It mints 25 test USDC into the vault, and your wallet signs nothing: the team's mint-only key signs the mint. It works once a UTC day per vault, for up to 3 vaults per signed-in account a day. When the server has no faucet key, the tab shows instead: "Need test USDC? Send @probarionhq a direct message on X with your vault's name." The rows that name Top-up API (faucet) cover the faucet's own answers, such as not_owner and mint_failed. The faucet also answers 503 not_configured when the server's faucet key does not parse or is not a mint-only key.

Messages that are not Probarion codes#

Related pages#

• How a payment is checked: the 14 spend checks, in the order that decides which code you get.
• Spend outcomes: the seven statuses process() returns, and the SDK's rule ids.
• Holds and approvals: the life of a held spend, behind NotHeld, HoldExpired and HoldNotExpired.
• Mandates: the limits behind the mandate codes.
• Vaults, roles and keys: who may call what, behind NotOwner, NotApprover, NotAgent and NotLedgerKey.
• Let an agent pay: the payment loop, refs and retries, and how to find a spend by its ref.
• The sources: contracts/vault/src/errors.rs (opens in a new tab), packages/sdk/src/errors.ts (opens in a new tab) and apps/web/src/lib/http.ts (opens in a new tab).