Errors - Sigil

Sigil’s JSON-RPC server returns errors using the JSON-RPC 2.0 error object:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "invalid params",
    "data": { "field": "amount", "reason": "negative_value" }
  },
  "id": 1
}

Error messages are sanitised before leaving the node. Absolute filesystem paths and host:port substrings are redacted by node/sigil-rpc/src/middleware.rs::sanitize_error_message.

Standard JSON-RPC codes

These follow JSON-RPC 2.0:

Code	Meaning	When
`-32700`	Parse error	Body is not valid JSON.
`-32600`	Invalid request	Envelope shape is wrong.
`-32601`	Method not found	Method is not in this RPC profile’s method table.
`-32602`	Invalid params	`params` failed type or range validation.
`-32603`	Internal error	Unexpected failure inside the node.

Sigil-specific codes

Code	Meaning	When
`-32001`	`InvalidSignature`	Signature did not verify against the public key and envelope.
`-32002`	`NonceMismatch`	Transaction nonce is not the next expected for the DID.
`-32003`	`InsufficientFunds`	DID does not have the balance required for the transaction.
`-32004`	`Expired`	`expires_at_height` is at or below the current height.
`-32005`	`RateLimited`	Source IP exceeded the rate limit.
`-32006`	`FeeTooLow`	Fee is below the local fee market acceptance threshold.
`-32007`	`MempoolFull`	Mempool is at capacity; retry with a higher fee.
`-32008`	`Reverted`	Transaction reverted during apply; `data` includes the revert reason.
`-32009`	`Unauthorised`	The signer lacks authority for this transaction.
`-32010`	`NotFound`	Requested record does not exist.
`-32011`	`Disputed`	Operation blocked because the target is in dispute.
`-32012`	`GasExceeded`	Wasmtime gas budget exhausted.
`-32013`	`StateRootMismatch`	Block header’s state root does not match the computed root.

Apply-time revert codes

When a transaction reverts during apply, error.code is -32008 and error.data.reason carries a domain-specific code. Examples:

Domain	Reason	Meaning
`transfer`	`recipient_not_found`	Recipient DID is not registered.
`dex`	`invariant_decreased`	Swap would decrease the constant-product invariant.
`dex`	`slippage_exceeded`	Output below `min_out` or input above `max_in`.
`nft`	`royalty_violation`	Sale price violates the royalty policy.
`name`	`already_registered`	Name has an active lease.
`name`	`reserved`	Name is on the genesis reserved list.
`mail`	`key_expired`	Recipient encryption key has expired.
`mail`	`policy_denied`	Mailbox policy rejected the delivery.
`mandate`	`delegation_too_deep`	Mandate delegation chain exceeds the depth limit.
`recovery`	`timelock_active`	Recovery is in its timelock window; abort is still possible.
`vigils`	`gas_tank_empty`	Subscription gas tank is empty.

Handling errors in clients

Pattern	Recommendation
`RateLimited`	Honour `Retry-After`; back off exponentially.
`NonceMismatch`	Re-fetch the account nonce with `sigil_getAccount`; re-sign.
`MempoolFull`	Increase fee or wait one block.
`Reverted`	Inspect `data.reason`; do not retry without changing inputs.
`Expired`	Set a longer `expires_at_height`; default is current height + 100.
`InsufficientFunds`	Re-fetch balance with `sigil_getBalance`; refund or top up.

The full list of revert reasons lives in each executor’s error enum (node/sigil-core/src/executor_*.rs::*Error). Treat the reason string as stable; codes will not be renamed without a deprecation cycle.

Reference

​Standard JSON-RPC codes

​Sigil-specific codes

​Apply-time revert codes

​Handling errors in clients

Standard JSON-RPC codes

Sigil-specific codes

Apply-time revert codes

Handling errors in clients