Skip to content

Add RPC error codes documentation (fixes bitcoin-dot-org/Bitcoin.org#1837)#332

Open
zp6 wants to merge 1 commit into
bitcoin-dot-org:masterfrom
zp6:docs/error-codes
Open

Add RPC error codes documentation (fixes bitcoin-dot-org/Bitcoin.org#1837)#332
zp6 wants to merge 1 commit into
bitcoin-dot-org:masterfrom
zp6:docs/error-codes

Conversation

@zp6
Copy link
Copy Markdown

@zp6 zp6 commented May 14, 2026

Summary

This PR adds comprehensive RPC error codes documentation to address bitcoin-dot-org/Bitcoin.org#1837.

Changes

New file: reference/rpc_error_codes.rst
A complete reference page documenting all Bitcoin Core RPC error codes, organized by category:

  • Standard JSON-RPC Errors (-32700 to -32603): Parse errors, invalid requests, method not found, invalid params, internal errors
  • General Application Errors (-1 to -32): Misc errors, type errors, invalid address/key, out of memory, invalid parameter, database errors, deserialization errors, verify errors, warmup, deprecated methods
  • P2P Client Errors (-9 to -34): Not connected, initial download, node management, invalid IP/subnet, P2P disabled, capacity reached
  • Chain Errors (-33): Mempool disabled
  • Wallet Errors (-4 to -36): Insufficient funds, keypool exhausted, encryption errors, wallet not found, wallet already loaded/exists
  • Block Validation Reject Reasons: Descriptive messages like bad-fork-prior-to-checkpoint (code 67), missing-inputs, insufficient-fee, etc.
  • Regtest Troubleshooting: Specific guidance for the bad-fork-prior-to-checkpoint error from the issue, plus other common regtest issues (removed generate command, wallet setup, insufficient funds)

Each error code includes:

  • Numeric code
  • Constant name
  • Description
  • Resolution/solution

Modified: reference/index.rst
Added rpc_error_codes to the toctree.

Modified: examples/testing.rst
Added a "Troubleshooting Regtest Errors" subsection with the example from the issue (bad-fork-prior-to-checkpoint (code 67)) and a link to the full error codes reference.

Error Code Source

Error codes are sourced from src/rpc/protocol.h in the Bitcoin Core repository.

Closes bitcoin-dot-org/Bitcoin.org#1837

Add comprehensive RPC error codes reference page including:
- JSON-RPC standard errors (-32700 to -32603)
- General application errors (-1 to -32)
- P2P client errors (-9 to -34)
- Chain errors (-33)
- Wallet errors (-4 to -36)
- Block validation reject reasons (bad-fork-prior-to-checkpoint, etc.)
- Regtest troubleshooting section

Also adds troubleshooting note to testing.rst with link to error codes page.

Error codes sourced from Bitcoin Core src/rpc/protocol.h.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add section with possible error codes and resolution suggestions

1 participant