Quicknode provides Logs for your RPC endpoints. Easily identify and resolve issues by viewing detailed error information directly from your dashboard.
How to read an RPC error
RPC failures are reported at two layers. HTTP errors indicate the request was rejected at the transport level—check for authentication, rate limits, payload size, or service availability. JSON-RPC errors mean the server received the request but couldn't complete the operation—read the error.code, message, and data fields together since codes can vary between node implementations.
- Check the HTTP status to rule out transport issues
- If the status is 200, look at
error.codein the response body - Read the
messageanddatafields for details - For persistent issues, review your Endpoint Logs
HTTP Error Codes
Let's look at the common HTTP Error Codes you can encounter, what they mean and what you can do to prevent them.
#
The endpoint rejected the HTTP request before it could process a normal RPC call.
Diagnose and resolve
Why it happens
- Malformed JSON, an invalid request body, or an unsupported HTTP request format.
- Using the wrong HTTP method or omitting the application/json content type.
- A request to a marketplace add-on or paid API that is not enabled for the endpoint can also return 400.
How to identify it
- Confirm that the HTTP status is 400, then read the response body for the parser or validation message.
- In Endpoint Logs, compare the recorded request method and body with the documented RPC request.
- For an add-on request, check the response message and confirm that the add-on is enabled for this endpoint; providers can use 400 rather than 403 for unavailable access.
How to resolve it
- Serialize the body with a JSON library and send the RPC request with POST and Content-Type: application/json.
- Validate that jsonrpc is "2.0", method is a string, params is an array or object, and id is valid.
- If the request requires an add-on, enable it for the endpoint and verify that the endpoint network is supported before retrying.
#
The request did not satisfy the authentication requirements configured for the endpoint.
#
The endpoint understood the request but refused to authorize it.
Diagnose and resolve
Why it happens
- An endpoint security rule denied the request, or the endpoint is disabled.
How to identify it
- Read the response message and inspect the matching Endpoint Log before changing credentials.
- Check IP allowlists, origin restrictions, method allowlists, and endpoint status.
How to resolve it
- Update the security rule only if the caller should be authorized; otherwise keep the request blocked.
- Re-enable the endpoint or contact support when the dashboard does not explain why it is disabled.
#
The HTTP route does not exist. An unknown JSON-RPC method normally appears as RPC error -32601 instead.
Diagnose and resolve
Why it happens
- A mistyped endpoint hostname, tokenized URL, path, or add-on route.
How to identify it
- Confirm that this is an HTTP 404 rather than a JSON-RPC response whose error code is -32601.
How to resolve it
- Copy the endpoint URL from the dashboard and verify any required REST or add-on path.
#
The request body is larger than the endpoint accepts.
Diagnose and resolve
Why it happens
- An oversized JSON-RPC batch or a request containing too much encoded data.
How to identify it
- Confirm the 413 HTTP status and measure the serialized request body, not only the number of application objects.
How to resolve it
- Split large batches into smaller requests and reduce unnecessary request data.
#
A request, connection, method, or add-on rate limit was reached.
Diagnose and resolve
Why it happens
- Plan-level request rate, a method-specific rule, concurrent connections, or an add-on allowance was exceeded.
- A JSON-RPC batch still counts each call inside the batch toward applicable limits.
How to identify it
- Read the response body to distinguish the limit and inspect usage around the same timestamp in the dashboard.
- Use Retry-After when the response supplies it.
How to resolve it
- Throttle requests, cap concurrency, and retry after the indicated delay with bounded backoff.
- Adjust an endpoint or method rate-limit rule, or change the plan/add-on allowance when sustained traffic requires it.
#
The server failed while processing the request.
Diagnose and resolve
Why it happens
- An unexpected failure occurred in the gateway, node client, or upstream service.
How to identify it
- Check whether identical read requests fail repeatedly and capture the timestamp, method, network, and response from Endpoint Logs.
How to resolve it
- Retry idempotent read requests with bounded backoff. Do not blindly resubmit a transaction without first checking whether it was accepted.
- If the error persists, send the non-secret request details and timestamp to support.
#
The endpoint or an upstream service is temporarily unable to handle the request.
HTTP Error Code Example
The code snippet below is an example of Error Code 429.
{
"jsonrpc": "2.0",
"error": {
"code": 429,
"message": "The requests per second (RPS) of your requests are higher than your plan allows."
},
"id": 1
}Zcash RPC Error Codes
Let's look at the common Zcash RPC Error Codes you can encounter, what they mean and what you can do to prevent them.
RPC#
Invalid JSON was received by the server.
Diagnose and resolve
Why it happens
- Malformed JSON syntax, truncated request, or encoding issues.
How to identify it
- The response id is typically null because the server could not parse the request.
How to resolve it
- Validate JSON syntax with a JSON linter before sending.
- Ensure proper quoting, commas, and bracket matching.
RPC#
The JSON is valid but does not conform to the JSON-RPC 2.0 Request structure.
Diagnose and resolve
Why it happens
- Missing or incorrect jsonrpc field, method is not a string, or invalid request shape.
How to identify it
- The JSON parsed successfully but failed validation as a Request object.
How to resolve it
- Ensure jsonrpc is "2.0", method is a string, and params is an array or object.
RPC#
The requested method does not exist or is not available.
Diagnose and resolve
Why it happens
- Misspelled method name, method not supported by this node, or add-on not enabled.
- Blockbook methods like bb_gettx require the Blockbook add-on.
How to identify it
- Verify the exact method name spelling and case sensitivity.
How to resolve it
- Use the documented method name exactly as specified.
- Enable required add-ons for extended functionality.
RPC#
One or more parameters are invalid for the requested method.
Diagnose and resolve
Why it happens
- Wrong parameter count, type, order, or format for the method.
How to identify it
- Read the error message for which parameter failed validation.
How to resolve it
- Compare parameters with the Bitcoin Core RPC documentation.
- Ensure correct types (strings, numbers, booleans) and formats.
RPC#
The server encountered an internal error while processing.
Diagnose and resolve
Why it happens
- An unexpected failure occurred within the Bitcoin node.
How to identify it
- Check if the same request fails repeatedly or is intermittent.
How to resolve it
- Retry with bounded backoff for transient issues.
- If persistent, contact support with the request details and timestamp.
RPC#
A general error that does not fit other categories.
Diagnose and resolve
Why it happens
- Various issues not covered by specific error codes.
How to identify it
- Read the error message for specific details.
How to resolve it
- Address the specific issue described in the error message.
RPC#
An unexpected type was passed as a parameter.
Diagnose and resolve
Why it happens
- Parameter type does not match the expected type for the method.
How to identify it
- Check which parameter has the wrong type in the error message.
How to resolve it
- Ensure parameter types match the method documentation (string, number, boolean, etc.).
RPC#
Unspecified problem with the wallet.
Diagnose and resolve
Why it happens
- Key not found, wallet file issue, or other wallet-related problem.
How to identify it
- Read the error message for wallet-specific details.
How to resolve it
- Verify the wallet is loaded and accessible.
- Check that the requested key or address exists in the wallet.
RPC#
The provided Bitcoin address or key is invalid.
Diagnose and resolve
Why it happens
- Malformed address format, wrong network (mainnet vs testnet), or invalid key encoding.
How to identify it
- Verify the address or key format against Bitcoin address standards.
How to resolve it
- Use a valid address for the correct network.
- Verify the address checksum and encoding.
RPC#
The wallet does not have enough funds for the operation.
Diagnose and resolve
Why it happens
- Account balance is less than the requested amount plus fees.
How to identify it
- Check wallet balance with getbalance or listunspent.
How to resolve it
- Reduce the transaction amount or add funds to the wallet.
- Account for transaction fees in your calculation.
RPC#
The node ran out of memory during the operation.
Diagnose and resolve
Why it happens
- Request too large or system memory exhausted.
How to identify it
- The error message mentions memory allocation failure.
How to resolve it
- Reduce the size of the request or batch.
- Check system memory availability.
RPC#
A parameter is invalid, missing, or duplicated.
Diagnose and resolve
Why it happens
- Required parameter missing, duplicate parameter provided, or value out of range.
How to identify it
- Read the error message for the specific parameter issue.
How to resolve it
- Provide all required parameters exactly once with valid values.
RPC#
The Bitcoin client is not connected to the network.
Diagnose and resolve
Why it happens
- Node has no peer connections or network is unavailable.
How to identify it
- Use getnetworkinfo to check connection status.
How to resolve it
- Wait for the node to establish peer connections.
- Check network configuration and firewall settings.
RPC#
The node is still downloading and verifying the blockchain.
Diagnose and resolve
Why it happens
- Initial block download (IBD) is in progress.
How to identify it
- Use getblockchaininfo to check sync progress.
How to resolve it
- Wait for the initial block download to complete.
- Some methods are unavailable until sync finishes.
RPC#
The specified label name is invalid.
Diagnose and resolve
Why it happens
- Label name contains invalid characters or format.
How to identify it
- Verify the label name format in the error message.
How to resolve it
- Use a valid label name without special characters.
RPC#
The keypool is exhausted and needs to be refilled.
Diagnose and resolve
Why it happens
- All pre-generated keys have been used.
How to identify it
- The error message mentions keypool exhaustion.
How to resolve it
- Call keypoolrefill to generate new keys.
- Unlock the wallet first if it is encrypted.
RPC#
The wallet must be unlocked to perform this operation.
Diagnose and resolve
Why it happens
- Wallet is encrypted and locked.
How to identify it
- The error message requests wallet passphrase.
How to resolve it
- Call walletpassphrase with the correct passphrase before retrying.
RPC#
The provided wallet passphrase is incorrect.
Diagnose and resolve
Why it happens
- Wrong passphrase entered for the encrypted wallet.
How to identify it
- The error explicitly mentions incorrect passphrase.
How to resolve it
- Retry with the correct passphrase.
- Passphrases are case-sensitive.
RPC#
Command given in wrong wallet encryption state.
Diagnose and resolve
Why it happens
- Attempting to encrypt an already encrypted wallet or similar conflict.
How to identify it
- Check current wallet encryption status with getwalletinfo.
How to resolve it
- Verify the wallet encryption state before running the command.
RPC#
Failed to encrypt the wallet.
Diagnose and resolve
Why it happens
- Encryption operation encountered an error.
How to identify it
- The error message provides encryption failure details.
How to resolve it
- Ensure the wallet is in a valid state for encryption.
- Check disk space and permissions.
RPC#
The wallet is already unlocked.
Diagnose and resolve
Why it happens
- Calling walletpassphrase when wallet is not locked.
How to identify it
- The error indicates the wallet is already unlocked.
How to resolve it
- No action needed—proceed with the intended operation.
RPC#
The specified wallet was not found.
Diagnose and resolve
Why it happens
- Wallet name is incorrect or wallet is not loaded.
How to identify it
- Use listwallets to see loaded wallets.
How to resolve it
- Load the wallet with loadwallet or use the correct wallet name.
RPC#
No wallet specified when multiple wallets are loaded.
Diagnose and resolve
Why it happens
- Multiple wallets loaded but request did not specify which one.
How to identify it
- Use listwallets to see all loaded wallets.
How to resolve it
- Specify the wallet in the RPC endpoint URL or use the wallet parameter.
RPC#
Database read/write error occurred.
Diagnose and resolve
Why it happens
- Disk corruption, permission issues, or database lock conflict.
How to identify it
- The error message provides database-specific details.
How to resolve it
- Check disk health and available space.
- Ensure no other process is locking the database.
RPC#
Error parsing or validating a structure in raw format.
Diagnose and resolve
Why it happens
- Malformed raw transaction hex, invalid block data, or encoding issues.
How to identify it
- Verify the raw hex data is complete and properly formatted.
How to resolve it
- Re-encode the transaction or data using a Bitcoin library.
- Ensure the hex string has no truncation or corruption.
RPC#
The specified node is already in the peer list.
Diagnose and resolve
Why it happens
- Attempting to add a peer that is already connected or added.
How to identify it
- Use getpeerinfo to check current peers.
How to resolve it
- No action needed—the node is already added.
RPC#
The specified node was not previously added.
Diagnose and resolve
Why it happens
- Attempting to remove a peer that is not in the added list.
How to identify it
- Use getaddednodeinfo to check added nodes.
How to resolve it
- Verify the node address before attempting removal.
RPC#
General error during transaction or block verification.
Diagnose and resolve
Why it happens
- Transaction or block failed initial verification checks.
How to identify it
- Read the error message for verification failure details.
How to resolve it
- Review and correct the transaction or block data.
- Ensure all inputs are valid and unspent.
RPC#
Transaction or block was rejected by network rules.
Diagnose and resolve
Why it happens
- Transaction violates consensus rules, double-spend attempt, or invalid signature.
How to identify it
- The error message contains the specific rejection reason.
How to resolve it
- Fix the issue identified in the rejection message.
- Do not resubmit the same invalid transaction.
RPC#
The transaction outputs are already in the UTXO set or the transaction is already confirmed.
Diagnose and resolve
Why it happens
- Attempting to submit a transaction that was already mined.
How to identify it
- Use gettransaction or getrawtransaction to check the transaction status.
How to resolve it
- No action needed—the transaction is already confirmed.
- Do not resubmit the same transaction.
RPC#
The node is still initializing and not ready for requests.
Diagnose and resolve
Why it happens
- Node is starting up and loading blockchain data.
How to identify it
- The error explicitly mentions warmup or initialization.
How to resolve it
- Wait for the node to complete initialization.
- Retry the request after a delay.
RPC#
The node to disconnect was not found in connected nodes.
Diagnose and resolve
Why it happens
- Attempting to disconnect a peer that is not currently connected.
How to identify it
- Use getpeerinfo to check current connections.
How to resolve it
- Verify the node address and connection status.
RPC#
The provided IP address or subnet is invalid.
Diagnose and resolve
Why it happens
- Malformed IP address or CIDR notation.
How to identify it
- Verify the IP address format in the error message.
How to resolve it
- Use valid IPv4 or IPv6 address format.
- For subnets, use correct CIDR notation (e.g., 192.168.1.0/24).
RPC#
No valid connection manager instance found.
Diagnose and resolve
Why it happens
- Node was started with P2P networking disabled.
How to identify it
- Check node startup configuration for network settings.
How to resolve it
- Restart the node with P2P networking enabled if peer operations are needed.
RPC#
The requested RPC method has been deprecated.
Diagnose and resolve
Why it happens
- Using an old method that has been replaced or removed.
How to identify it
- The error message indicates the method is deprecated.
How to resolve it
- Check the Bitcoin Core release notes for the replacement method.
- Update your code to use the current API.
RPC#
The mempool is disabled on this node.
Diagnose and resolve
Why it happens
- Node was started with -blocksonly or mempool disabled.
How to identify it
- The error indicates mempool functionality is unavailable.
How to resolve it
- Use an endpoint with mempool enabled for transaction-related operations.
RPC#
Maximum number of peer connections reached.
Diagnose and resolve
Why it happens
- The node has reached its configured maximum peer limit.
How to identify it
- Use getpeerinfo to check current connection count.
How to resolve it
- Wait for existing connections to close or increase maxconnections.
RPC#
The specified wallet is already loaded.
Diagnose and resolve
Why it happens
- Attempting to load a wallet that is already open.
How to identify it
- Use listwallets to see currently loaded wallets.
How to resolve it
- No action needed—the wallet is already available.
RPC#
A wallet with this name already exists.
Diagnose and resolve
Why it happens
- Attempting to create a wallet with an existing name.
How to identify it
- Check the wallet directory for existing wallet files.
How to resolve it
- Use a different wallet name or load the existing wallet instead.
RPC#
A request limit was exceeded.
Diagnose and resolve
Why it happens
- Query range, result size, or other limit exceeded.
How to identify it
- The error message specifies which limit was hit.
How to resolve it
- Reduce the query range or batch size.
- Paginate large requests.
Quicknode#
The endpoint exceeded its configured or plan-level per-second request allowance.
Diagnose and resolve
Why it happens
- The aggregate request rate crossed the per-second limit.
How to identify it
- Confirm Quicknode RPC code -32007 and correlate the timestamp with request-rate metrics.
How to resolve it
- Throttle the caller, cap concurrency, and spread burst traffic over time.
- Increase the applicable limit or plan capacity when the sustained request rate requires it.
Quicknode#
The endpoint exceeded its configured or plan-level per-minute request allowance.
Diagnose and resolve
Why it happens
- The aggregate request count crossed the rolling per-minute limit.
How to identify it
- Confirm Quicknode RPC code -32008 and compare the timestamp with request metrics over a full minute.
How to resolve it
- Queue or throttle requests so bursts remain below the per-minute allowance.
- Increase the applicable limit or plan capacity when the sustained request volume requires it.
Quicknode#
A method-specific rate-limit rule rejected the request.
Diagnose and resolve
Why it happens
- Calls to the named RPC method exceeded its configured limit.
How to identify it
- Confirm Quicknode RPC code -32011, then use Endpoint Logs to identify the method and matching rate-limit rule.
How to resolve it
- Reduce or cache calls to that method, or update the method rule if the traffic is expected.
Quicknode#
The request is missing required JSON-RPC envelope fields or has an invalid structure.
Diagnose and resolve
Why it happens
- The JSON-RPC envelope is incomplete—missing jsonrpc, method, or id fields.
- The request was routed to an internal parser that expects a different format.
- The method field is empty or missing.
How to identify it
- Confirm source Quicknode and code -32604; do not confuse it with standard JSON-RPC -32601 (method not found).
- Check if the error message mentions missing fields like jsonrpc, id, or type.
How to resolve it
- Include the complete JSON-RPC 2.0 envelope: jsonrpc, method, params, and id fields.
- Ensure jsonrpc is set to "2.0", method is a non-empty string, and id is present.
Quicknode#
The request was rejected by an endpoint security filter, such as a method allowlist or blocklist. Review the endpoint's request filter settings.
Diagnose and resolve
Why it happens
- A method or request filter configured on the endpoint denied the request.
How to identify it
- Confirm source Quicknode and code -32611, then match the method and caller with the endpoint security rules.
How to resolve it
- Allow the request only if it is intended; otherwise keep the filter in place and correct the caller.
Quicknode#
The request exceeded a rate limit. This code may appear for method-specific or connection-based limits.
Diagnose and resolve
Why it happens
- The request rate for a specific method or connection exceeded the configured limit.
How to identify it
- Confirm source Quicknode and code -32029. Check the error message for retry timing.
How to resolve it
- Wait for the indicated retry period before sending another request.
- Reduce request frequency or implement exponential backoff.
Zcash RPC Error Code Example
The code snippet below is an example of Error Code -32601.
{
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": "Method not found"
},
"id": 1
}Endpoint Logs
Quicknode provides logs for your RPC endpoints to help you diagnose issues. You can view logs directly in your Quicknode dashboard by navigating to:
- Endpoints in the sidebar
- Selecting your endpoint
- Opening the Logs tab
You can filter logs by time window, response type, method, and network.
What Gets Logged
Endpoint Requests
Requests made to your endpoint, including the HTTP status, request method, RPC method or path, and timestamp.
Error Details
When available, failed requests include error details such as RPC error codes, request and response bodies, and links to related documentation.
Logging Limitations
Log availability can vary by method, response type, network, and plan. To maintain optimal endpoint performance, logging operates on a best-effort basis. Some logs may be dropped during high-traffic periods to preserve low latency.
Diagnose an Error From Its Log
Use the matching log entry to compare the request and response before changing your integration.
- Filter to the smallest time window, method, and network that contain the failed request.
- Check the HTTP status first. If the response body contains a JSON-RPC error object, record its code, message, and data separately.
- Compare the logged request method and parameters with the method reference. For implementation-defined RPC codes, the message and data are required to identify the cause.
- Keep the timestamp and request ID when escalating an issue, but redact endpoint tokens, authorization headers, private keys, and signed payloads that should not be shared.
Retention and Access
Build and Scale plans include dashboard access with standard log retention. Enterprise plans provide extended retention periods and programmatic log retrieval through the Admin API.
For service availability or active incidents, check the Quicknode Status Page.
If you're experiencing other error codes, please let us know by submitting a ticket. We're more than happy to assist