Add error codes documentation with resolution suggestions

examples/testing.rst

@@ -51,3 +51,153 @@ Verify that we now have 50 bitcoins available to spend.
 You can now use Bitcoin Core `RPCs <../reference/rpc/index.html>`__ prefixed with ``bitcoin-cli -regtest``.
 
 Regtest wallets and block chain state (chainstate) are saved in the ``regtest`` subdirectory of the Bitcoin Core configuration directory. You can safely delete the ``regtest`` subdirectory and restart Bitcoin Core to start a new regtest. (See the `Developer Examples Introduction <../examples/index.html>`__ for default configuration directory locations on various operating systems. Always back up mainnet wallets before performing dangerous operations such as deleting.)
+
+Common Error Codes
+~~~~~~~~~~~~~~~~~~
+
+When developing and testing with Bitcoin Core, you may encounter various error codes. Understanding these errors and their resolutions can help you debug issues more efficiently.
+
+Block Validation Errors
+^^^^^^^^^^^^^^^^^^^^^^^
+
+These errors occur when Bitcoin Core rejects a block during validation:
+
+.. list-table::
+   :widths: 15 30 55
+   :header-rows: 1
+
+   * - Code
+     - Error Message
+     - Resolution
+   * - 16
+     - ``bad-txns-vin-empty``
+     - Transaction has no inputs. Ensure all transactions have at least one input.
+   * - 17
+     - ``bad-txns-vout-empty``
+     - Transaction has no outputs. Ensure all transactions have at least one output.
+   * - 18
+     - ``bad-txns-oversize``
+     - Transaction exceeds maximum allowed size. Split into smaller transactions.
+   * - 26
+     - ``bad-txns-vout-negative``
+     - Output value is negative. Ensure all output values are non-negative.
+   * - 27
+     - ``bad-txns-vout-toolarge``
+     - Output value exceeds maximum allowed (21 million BTC). Check output amounts.
+   * - 64
+     - ``bad-blk-length``
+     - Block exceeds maximum size limit. In regtest, check your block generation parameters.
+   * - 67
+     - ``bad-fork-prior-to-checkpoint``
+     - Block forks the chain before a checkpoint. In regtest mode, this typically means you're trying to reorganize past a hardcoded checkpoint. Solution: Delete the regtest data directory and start fresh, or ensure you're not mixing mainnet/testnet checkpoints with regtest.
+   * - 68
+     - ``bad-diffbits``
+     - Block has incorrect difficulty bits. Verify proof-of-work calculation.
+
+RPC Error Codes
+^^^^^^^^^^^^^^^
+
+These errors are returned by Bitcoin Core's JSON-RPC interface:
+
+.. list-table::
+   :widths: 15 35 50
+   :header-rows: 1
+
+   * - Code
+     - Error Message
+     - Resolution
+   * - -1
+     - ``RPC_MISC_ERROR``
+     - Generic error. Check the error message for details.
+   * - -3
+     - ``RPC_TYPE_ERROR``
+     - Unexpected argument type. Verify parameter types match the RPC specification.
+   * - -5
+     - ``RPC_INVALID_ADDRESS_OR_KEY``
+     - Invalid Bitcoin address or key. Verify the address format and network (mainnet vs testnet vs regtest).
+   * - -6
+     - ``RPC_OUT_OF_MEMORY``
+     - Not enough memory. Increase available RAM or reduce Bitcoin Core memory usage with ``-dbcache``.
+   * - -8
+     - ``RPC_INVALID_PARAMETER``
+     - Invalid or missing parameter. Check the RPC documentation for required parameters.
+   * - -25
+     - ``RPC_VERIFY_ERROR``
+     - Transaction or block verification failed. Check transaction inputs and signatures.
+   * - -26
+     - ``RPC_VERIFY_REJECTED``
+     - Transaction rejected by network rules. Common causes: insufficient fee, non-standard transaction, or double-spend attempt.
+   * - -27
+     - ``RPC_VERIFY_ALREADY_IN_CHAIN``
+     - Transaction already in blockchain. This is informational, not an actual error.
+   * - -28
+     - ``RPC_IN_WARMUP``
+     - Bitcoin Core is still starting. Wait for initialization to complete before making RPC calls.
+
+Wallet Error Codes
+^^^^^^^^^^^^^^^^^^
+
+Errors specific to wallet operations:
+
+.. list-table::
+   :widths: 15 35 50
+   :header-rows: 1
+
+   * - Code
+     - Error Message
+     - Resolution
+   * - -4
+     - ``RPC_WALLET_ERROR``
+     - Generic wallet error. Check that wallet is loaded and not encrypted/locked.
+   * - -12
+     - ``RPC_WALLET_KEYPOOL_RAN_OUT``
+     - Keypool is exhausted. Run ``keypoolrefill`` to generate new keys.
+   * - -13
+     - ``RPC_WALLET_UNLOCK_NEEDED``
+     - Wallet is encrypted and locked. Use ``walletpassphrase`` to unlock.
+   * - -14
+     - ``RPC_WALLET_PASSPHRASE_INCORRECT``
+     - Incorrect wallet passphrase. Verify the passphrase is correct.
+   * - -17
+     - ``RPC_WALLET_NOT_FOUND``
+     - Wallet not found. Load the wallet with ``loadwallet`` or create a new one.
+   * - -18
+     - ``RPC_WALLET_NOT_SPECIFIED``
+     - Multiple wallets loaded but none specified. Use the ``-rpcwallet`` option or specify wallet in the RPC URL.
+
+Network Error Codes
+^^^^^^^^^^^^^^^^^^^
+
+Errors related to peer-to-peer networking:
+
+.. list-table::
+   :widths: 15 35 50
+   :header-rows: 1
+
+   * - Code
+     - Error Message
+     - Resolution
+   * - -9
+     - ``RPC_CLIENT_NOT_CONNECTED``
+     - Bitcoin Core is not connected to any peers. Check network connectivity and firewall settings.
+   * - -10
+     - ``RPC_CLIENT_IN_INITIAL_DOWNLOAD``
+     - Node is still syncing the blockchain. Wait for initial block download to complete.
+
+Debugging Tips
+^^^^^^^^^^^^^^
+
+When encountering errors:
+
+1. **Check the debug log**: Bitcoin Core writes detailed logs to ``debug.log`` in the data directory. This often contains more context about errors.
+
+2. **Use ``-printtoconsole``**: Start bitcoind with this flag to see log output in real-time.
+
+3. **Verify network mode**: Ensure you're using the correct network flag (``-regtest``, ``-testnet``, or mainnet) consistently across all commands.
+
+4. **Reset regtest state**: For persistent regtest issues, delete the ``regtest`` subdirectory and start fresh::
+
+       rm -rf ~/.bitcoin/regtest
+       bitcoind -regtest -daemon
+
+5. **Check RPC connectivity**: Verify RPC settings with ``bitcoin-cli -regtest getnetworkinfo``.