Errors

A failed execute returns an ExtrinsicResult whose error has a semantic code (branch on it) and a remediation hint (what to try next). Every chain error name is deliberately classified — a CI gate keeps the mapping complete in both directions. Each code has its own explainer page listing the chain errors that map to it, and every exact chain error name has its own page under chain errors. The machine-readable version is at /catalog/errors.json.

Code	Chain errors	Remediation
insufficient_balance	25	Fund the signing account or reduce the amount; check with btcli wallet balance
insufficient_liquidity	8	The pool cannot absorb this trade; reduce the amount or split it into smaller steps
rate_limited	17	Wait for the rate-limit window to pass, then retry
not_registered	4	Register the hotkey on this subnet first with btcli subnets register
not_authorized	22	Sign with the key or origin that owns the target object, then retry
already_exists	27	The object or state already exists; treat the goal as met or pick a different target
not_found	20	The referenced object is not on-chain; check the identifier
subnet_not_exists	4	Use an existing netuid; btcli subnets list shows valid ones
subtoken_disabled	1	The subnet is not active yet; wait for start_call
disabled	17	This call or feature is switched off on this network
too_early	18	The required window has not opened yet; wait some blocks and retry
expired	5	The window has closed; restart the flow with fresh state
limit_exceeded	35	A chain-side capacity limit was hit; reduce the size or count of the request
unit_mismatch	—	Match the Balance netuid to the operation's currency
invalid_argument	137	Check the argument values against the operation schema
policy_violation	1	The action exceeds a configured safety policy
internal	19	A chain-side invariant failed; nothing to fix client-side — report it if it persists
unknown	—	Inspect the message for details