Errors and error codes#
When something fails, VOOL classifies the failure and shows you a message that says what happened, what did not happen, and what to do. Many surfaces also carry the stable machine code for the failure (in receipts, diagnostics and bug reports) — this page is its reference.
Reading an error#
Three facts matter before you retry anything:
- What happened — the message. It never contains internal paths or secrets.
- What may already have happened — some refusals stop before anything is sent or changed; some failures genuinely cannot say whether an action completed. Where the outcome is unknown, the message says so and tells you to check state before retrying — never to blindly re-send (a duplicate payment is exactly the harm this avoids).
- The recovery action — the concrete next step, not a shrug.
A fourth fact is transport, not meaning: an HTTP status (401, 403, 429, 500) tells you how a request fared on the wire. It is never, by itself, an explanation. VOOL keeps the two apart: 403 did not tell you why — the code does.
The codes, and where the full reference lives#
Codes are language-independent and stable across releases: a code is never renamed or reused for a different meaning. The catalog reference — each declared catalog code with its title, meaning, severity, retryability, effect state and recovery — is the Error Book, which is generated from the runtime's own fault catalog and is checked for drift against it. Each catalog code has its own section there whose heading is the code itself (the stable link form: the book's URL, #, and the code with underscores as hyphens), and searching that page for the code as written finds its section.
Codes you are most likely to see:
| Code | Title | What may already have happened |
|---|---|---|
permission_denied | Permission denied | Nothing was changed. |
provider_unavailable | Provider unreachable | Nothing billable left your machine. |
provider_exhausted | Provider limit reached | A request reached the provider. |
timeout | Timed out | Unknown — check state before retrying. |
credential_failure | Stored credential could not be read | Nothing. |
wallet_quote_mismatch | Approval no longer matches the preview | Nothing was signed or sent. |
wallet_broadcast_failed | Payment could not be broadcast | Unknown — check its status before retrying. |
wallet_duplicate_payment | Payment already proposed or sent | An earlier proposal exists on record. |
Distinguishing failures from other outcomes#
These are not interchangeable, and VOOL's wording keeps them apart:
- An error — something failed; the code and message say what and what to do.
- Waiting for approval — a permission request or payment confirmation is waiting for you. Nothing has run and nothing will until you answer.
- Paused by a price guard or spend cap — the refusal happened before the provider was contacted. The message never implies the provider was asked.
- Cancelled — you (or the runtime) stopped it. Not a failure.
- Unsupported — this build does not do that (for example, in-process EVM custody). The message names the supported alternative.
- Incomplete/unknown outcome — the action may or may not have completed (a timeout after dispatch, a payment whose broadcast result never arrived). Check state first; the supported resume path never re-pays blindly.
A code you don't recognise#
An unknown code is either from a different build or not from VOOL at all. Check the build identity on the receipt, search the Error Book, and if it is genuinely from this build, report it with the code as written — the unexpected-error fallback always keeps a safe reference id (fault-…) you can quote. Unknown failures are recorded honestly as unknown; they are never dressed up as a known, "fixed" cause.
Spending refusals are pre-send#
When a spend cap or your accepted price refuses a call, the refusal happens before the provider is contacted. The message will never imply the provider was asked — see Spending limits.
Troubleshooting specific symptoms#
See Troubleshooting for install, model and platform problems, and Backup and recovery for the supported recovery paths.
Coverage and language limits#
This candidate reference has 54 catalog-code sections. Another 16 boundary registries list 118 codes in the boundary matrix; those do not all have individual sections. The coverage check uses static extraction of declared codes and known emission sites. It does not prove universal error coverage or classify every future failure.
The manual currently has 36 English pages and two pages each in Lithuanian and Chinese. The full manual and Error Book are not fully translated. A language choice is not a promise that this page exists in that language.