RPC Error Codes

JSON-RPC errors from tidecoind follow the Bitcoin Core code layout (negative integer code, human-readable message, optional data). Integrators should handle the common ones explicitly: RPC method not found (-32601), invalid params (-32602), wallet not loaded (-18), insufficient funds (-6), transaction rejected (-26 with policy-specific reason strings).

This page is the error-code reference. It is not a list of every possible human-readable message. Messages can include validation reasons, wallet details, or policy strings; integrations should branch on code first and use message for operator detail.

JSON-RPC standard errors

Code	Name	Meaning	Retry guidance
`-32700`	`RPC_PARSE_ERROR`	Request JSON could not be parsed.	Do not retry unchanged. Fix request encoding.
`-32600`	`RPC_INVALID_REQUEST`	Request object is not valid JSON-RPC.	Do not retry unchanged. Fix request shape.
`-32601`	`RPC_METHOD_NOT_FOUND`	Method does not exist on this node.	Do not retry unchanged. Check version, wallet endpoint, and spelling.
`-32602`	`RPC_INVALID_PARAMS`	Invalid JSON-RPC parameters.	Do not retry unchanged. Fix params.
`-32603`	`RPC_INTERNAL_ERROR`	Internal node error.	Retry only after checking node logs and health.

General application errors

Code	Name	Meaning	Typical Tidecoin examples
`-1`	`RPC_MISC_ERROR`	General exception or miscellaneous failure.	Unexpected command handling failure.
`-3`	`RPC_TYPE_ERROR`	Parameter type is wrong.	Passing object where string/number is expected.
`-5`	`RPC_INVALID_ADDRESS_OR_KEY`	Address, key, or hash-like identifier is invalid.	Invalid Tidecoin payout address in `createauxblock`; invalid wallet address.
`-7`	`RPC_OUT_OF_MEMORY`	Operation ran out of memory.	Large request or stressed node.
`-8`	`RPC_INVALID_PARAMETER`	Parameter value is syntactically valid but unacceptable.	PQHD seed is not 32-byte hex; no scheme provided to `setpqhdpolicy`.
`-20`	`RPC_DATABASE_ERROR`	Database operation failed.	Wallet DB or index DB failure.
`-22`	`RPC_DESERIALIZATION_ERROR`	Raw hex or serialized structure could not be parsed.	Invalid raw transaction, block, PSBT, or AuxPoW hex.
`-25`	`RPC_VERIFY_ERROR`	General verification failure.	Block or transaction verification failed.
`-26`	`RPC_VERIFY_REJECTED`	Transaction or block rejected by consensus or policy.	Mempool rejection, invalid block, invalid AuxPoW.
`-27`	`RPC_VERIFY_ALREADY_IN_UTXO_SET`	Transaction already confirmed.	Duplicate transaction submission.
`-28`	`RPC_IN_WARMUP`	Node is still warming up.	Startup or reindex warmup.
`-32`	`RPC_METHOD_DEPRECATED`	Method is deprecated.	Client uses an old RPC workflow.

P2P and chain-state errors

Code	Name	Meaning	Retry guidance
`-9`	`RPC_CLIENT_NOT_CONNECTED`	Node has no required P2P connectivity.	Retry after peers connect.
`-10`	`RPC_CLIENT_IN_INITIAL_DOWNLOAD`	Node is in initial block download.	Retry after sync, except for regtest/on-demand workflows.
`-23`	`RPC_CLIENT_NODE_ALREADY_ADDED`	Peer is already in the added-node list.	Treat as idempotent or remove first.
`-24`	`RPC_CLIENT_NODE_NOT_ADDED`	Peer was not previously added.	Do not retry unchanged.
`-29`	`RPC_CLIENT_NODE_NOT_CONNECTED`	Requested peer is not connected.	Retry only after checking peer state.
`-30`	`RPC_CLIENT_INVALID_IP_OR_SUBNET`	Invalid IP or subnet parameter.	Fix parameter.
`-31`	`RPC_CLIENT_P2P_DISABLED`	P2P connection manager is unavailable.	Check node startup flags.
`-33`	`RPC_CLIENT_MEMPOOL_DISABLED`	Mempool is unavailable.	Check node mode and command requirements.
`-34`	`RPC_CLIENT_NODE_CAPACITY_REACHED`	Outbound or block-relay connection limit reached.	Retry after capacity changes or disconnects.

Wallet errors

Code	Name	Meaning	Typical handling
`-4`	`RPC_WALLET_ERROR`	General wallet failure.	Show message to operator; inspect wallet state.
`-6`	`RPC_WALLET_INSUFFICIENT_FUNDS`	Wallet lacks spendable funds.	Do not retry unchanged.
`-11`	`RPC_WALLET_INVALID_LABEL_NAME`	Label name is invalid.	Fix label.
`-12`	`RPC_WALLET_KEYPOOL_RAN_OUT`	Wallet keypool is exhausted.	Refill or unlock wallet as required.
`-13`	`RPC_WALLET_UNLOCK_NEEDED`	Wallet must be unlocked first.	Unlock with `walletpassphrase` if operational policy allows.
`-14`	`RPC_WALLET_PASSPHRASE_INCORRECT`	Wallet passphrase is wrong.	Do not retry blindly.
`-15`	`RPC_WALLET_WRONG_ENC_STATE`	Command does not match wallet encryption state.	Check whether wallet is encrypted/unlocked.
`-16`	`RPC_WALLET_ENCRYPTION_FAILED`	Wallet encryption failed.	Stop and inspect wallet/logs.
`-17`	`RPC_WALLET_ALREADY_UNLOCKED`	Wallet is already unlocked.	Treat as idempotent where safe.
`-18`	`RPC_WALLET_NOT_FOUND`	Requested wallet is not loaded or does not exist.	Check `-rpcwallet`, `listwallets`, and wallet path.
`-19`	`RPC_WALLET_NOT_SPECIFIED`	Multiple wallets are loaded and no wallet was selected.	Add `-rpcwallet="<wallet>"`.
`-35`	`RPC_WALLET_ALREADY_LOADED`	Wallet is already loaded.	Treat as idempotent where safe.
`-36`	`RPC_WALLET_ALREADY_EXISTS`	Wallet name/path already exists.	Choose another name or load existing wallet.

Tidecoin-specific messages

Tidecoin-specific commands generally use the standard codes above with Tidecoin-specific messages.

Area	Common code	Message pattern
AuxPoW payout address	`-5`	Invalid coinbase payout address.
AuxPoW candidate/submission	`-25` / `-26`	Candidate creation, proof, or block validation failed.
PQHD seed import	`-8`	Seed must be 32-byte hex.
PQHD policy	`-8` / `-4`	Missing scheme, unknown scheme, unsupported wallet policy, or wallet write failure.
PQHD seed selection/removal	`-4`	Seed not present, default seed cannot be removed, or seed is referenced by descriptors.
Wallet-assisted AuxPoW	`-4`	Private keys are disabled for this wallet.

Integration guidance

Treat -32602, -8, -5, and -22 as client/request bugs unless the input was generated by an untrusted external party.
Treat -9, -10, and -28 as node-state errors that may clear later.
Treat -26 as a rejection and store the message for debugging.
Always pass -rpcwallet or wallet endpoint selection when multiple wallets may be loaded.
Do not parse human-readable messages as stable API unless a specific integration contract says so.