MultiChain JSON-RPC API errors

Identifying what happened when things go wrong

If an error occurs when processing a MultiChain API request, an error code is returned in a standard JSON-RPC error object. This object has two fields – code containing a numerical identifier for the error, and message containing a verbal description of its cause.

If you are using multichain-cli, both the error code and message will be displayed in the terminal window. If you are using the JSON-RPC API directly, your application should catch these errors and deal with them as appropriate.

In production releases of MultiChain, your application can assume that the code identifier for each type of error will not change. However the message strings are likely to change in future versions of MultiChain, and your application should not assume otherwise.

A full list of error codes and their meaning is provided below, alongside the name used for the error in MultiChain’s source code.

JSON-RPC processing errors

Code	Name	Description
`-32600`	`RPC_INVALID_REQUEST`	The JSON sent is not a valid JSON-RPC request object.
`-32601`	`RPC_METHOD_NOT_FOUND`	The `method` specified in the JSON-RPC request is not available in MultiChain.
`-32602`	`RPC_INVALID_PARAMS`	The parameters provided in the JSON-RPC request are not valid for the method that was called. In practice, this is not used – see instead `RPC_INVALID_PARAMETER` below.
`-32603`	`RPC_INTERNAL_ERROR`	An internal error occurred while processing the JSON-RPC request (you should report this to us).
`-32700`	`RPC_PARSE_ERROR`	The message sent cannot be parsed as a JSON-formatted string.

General application errors (from Bitcoin Core)

`-1`	`RPC_MISC_ERROR`	A general exception occurred.
`-2`	`RPC_FORBIDDEN_BY_SAFE_MODE`	MultiChain is in safe mode (not documented), and this command is not allowed in safe mode.
`-3`	`RPC_TYPE_ERROR`	An unexpected type was passed as a parameter.
`-5`	`RPC_INVALID_ADDRESS_OR_KEY`	An invalid address, public key or private key was passed as a parameter.
`-7`	`RPC_OUT_OF_MEMORY`	MultiChain ran out of memory while performing the operation.
`-8`	`RPC_INVALID_PARAMETER`	An invalid value was passed as a parameter.
`-20`	`RPC_DATABASE_ERROR`	An error occurred in MultiChain’s internal database (you should report this to us).
`-22`	`RPC_DESERIALIZATION_ERROR`	Error in parsing or validating a data structure that was provided in hexadecimal or base64 format.
`-25`	`RPC_TRANSACTION_ERROR`	General error while verifying a submitted transaction or block (for now, if not signed properly).
`-26`	`RPC_TRANSACTION_REJECTED`	Transaction or block was rejected by the blockchain network’s rules.
`-27`	`RPC_TRANSACTION_ALREADY_IN_CHAIN`	Transaction rejected because it is already in the blockchain.
`-28`	`RPC_IN_WARMUP`	MultiChain is still warming up and cannot yet response to this request.

General application errors (MultiChain specific)

`-701`	`RPC_NOT_ALLOWED`	The requested action is not permitted for the entity or blockchain.
`-702`	`RPC_NOT_SUPPORTED`	Action is not supported under these blockchain parameters or runtime parameters.
`-703`	`RPC_NOT_SUBSCRIBED`	This node is not subscribed to the specified asset or stream.
`-704`	`RPC_INSUFFICIENT_PERMISSIONS`	Address has insufficient permissions for the operation requested.
`-705`	`RPC_DUPLICATE_NAME`	An entity with this name already exists on the blockchain.
`-706`	`RPC_UNCONFIRMED_ENTITY`	The referred entity has not yet been confirmed (relevant for deprecated protocols).
`-707`	`RPC_EXCHANGE_ERROR`	An invalid exchange transaction was passed to one of the exchange APIs.
`-708`	`RPC_ENTITY_NOT_FOUND`	The asset or stream reference in an API request or transaction was not found.
`-709`	`RPC_WALLET_ADDRESS_NOT_FOUND`	The address provided was not found in the local node’s wallet.
`-710`	`RPC_TX_NOT_FOUND`	The specified transaction (by txid) was not found.
`-711`	`RPC_BLOCK_NOT_FOUND`	The specified block (by height or hash) was not found.
`-712`	`RPC_OUTPUT_NOT_FOUND`	The specified (unspent) transaction output was not found.
`-713`	`RPC_OUTPUT_NOT_DATA`	The specified transaction output does not contain any metadata to retrieve.
`-714`	`RPC_INPUTS_NOT_MINE`	None of the inputs in this transaction (to be disabled) belong to this node’s wallet.
`-715`	`RPC_WALLET_OUTPUT_NOT_FOUND`	The specified (unspent) transaction output was not found in this node’s wallet.
`-716`	`RPC_WALLET_NO_UNSPENT_OUTPUTS`	This node’s wallet contains no unspent outputs for creating a new transaction.
`-717`	`RPC_GENERAL_FILE_ERROR`	An error occurred when accessing the file path provided.
`-718`	`RPC_UPGRADE_REQUIRED`	This blockchain has been upgraded and requires a more recent version of MultiChain.

Peer-to-peer client errors

`-9`	`RPC_CLIENT_NOT_CONNECTED`	Operation not allowed because MultiChain is not connected to any other nodes.
`-10`	`RPC_CLIENT_IN_INITIAL_DOWNLOAD`	Operation not allowed because MultiChain is still downloading the initial block chain.
`-23`	`RPC_CLIENT_NODE_ALREADY_ADDED`	The node requested to be manually added has already been added before.
`-24`	`RPC_CLIENT_NODE_NOT_ADDED`	This node was not manually added, so the requested information cannot be provided.

Wallet errors

`-4`	`RPC_WALLET_ERROR`	A general error occurred with the node’s wallet (you should report this to us).
`-6`	`RPC_WALLET_INSUFFICIENT_FUNDS`	The wallet or address has insufficient funds for this transaction.
`-11`	`RPC_WALLET_INVALID_ACCOUNT_NAME`	An invalid account name was specified (note that accounts are deprecated).
`-12`	`RPC_WALLET_KEYPOOL_RAN_OUT`	The wallet’s key pool ran out (please report this to us).
`-13`	`RPC_WALLET_UNLOCK_NEEDED`	This operation requires the wallet to be unlocked using the `walletpassphrase` command.
`-14`	`RPC_WALLET_PASSPHRASE_INCORRECT`	An incorrect wallet passphrase was provided.
`-15`	`RPC_WALLET_WRONG_ENC_STATE`	A command was given in the wrong wallet encryption state.
`-16`	`RPC_WALLET_ENCRYPTION_FAILED`	The wallet could not be encypted (you should report this to us).