Quicknode provides Error 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 custom trace code is not whitelisted for this endpoint.
Diagnose and resolve
Why it happens
- The trace code has not been approved through the Quicknode approval process.
- The trace method requires a specific add-on or plan that is not enabled.
How to identify it
- Confirm the 403 status and check if the error message mentions custom trace or whitelisting.
How to resolve it
- Submit a support ticket to request approval for the custom trace code.
- Verify that your plan supports custom tracing and the required add-on is enabled.
#
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
}Solana RPC Error Codes
Let's look at the common Solana RPC Error Codes you can encounter, what they mean and what you can do to prevent them.
RPC#
The requested slot is older than the first block retained by the RPC node.
Diagnose and resolve
Why it happens
- The node has already removed the requested block from its local ledger.
How to identify it
- Read the requested slot and firstAvailableBlock values from the error message.
How to resolve it
- Correct the slot if it is wrong, or query an endpoint that retains the required historical block.
RPC#
The preflight simulation performed by sendTransaction failed. The RPC message is a wrapper; the actionable failure is in error.data.
Diagnose and resolve
Why it happens
- The simulated transaction produced a TransactionError, such as BlockhashNotFound or an InstructionError.
How to identify it
- Inspect error.data.err for the structured transaction error and error.data.logs for the program log immediately before the failure.
- Use the instruction index in InstructionError to find the failing instruction in the submitted transaction.
How to resolve it
- Fix the specific transaction or instruction error shown in data.err and the logs, then rebuild and re-sign the transaction.
- Only fetch a fresh blockhash and retry when the nested error is BlockhashNotFound; -32002 alone is not a retry signal.
RPC#
The transaction did not pass signature verification. On Agave 3.1 and later, simulateTransaction and sendTransaction preflight report SignatureFailure inside the simulation result instead of returning RPC -32003.
Diagnose and resolve
Why it happens
- A required signature is missing or invalid, or the transaction message changed after it was signed.
How to identify it
- Account for both forms: RPC code -32003 on older implementations and SignatureFailure in the simulation result err field on current Agave.
How to resolve it
- Rebuild the final transaction message and collect valid signatures from every required signer after all message fields are finalized.
RPC#
The RPC node cannot return a block for the requested slot.
Diagnose and resolve
Why it happens
- The block is not yet available from the node or is not present in its retained history.
How to identify it
- The Agave error message includes the unavailable slot number.
How to resolve it
- For a recent slot, wait for the requested commitment and retry with bounded backoff. For an old slot, verify that the endpoint retains the required history.
RPC#
The RPC node considers itself unhealthy; when known, error.data.numSlotsBehind reports how far it is behind.
Diagnose and resolve
Why it happens
- The node is not sufficiently synchronized with the cluster.
How to identify it
- Inspect error.data.numSlotsBehind. The field can be null when the distance is not available.
How to resolve it
- Retry the read with bounded backoff. If the condition persists on a Quicknode endpoint, capture the Endpoint Log and contact support.
RPC#
A transaction failed verification for a native precompile instruction.
Diagnose and resolve
Why it happens
- A precompile instruction contains invalid signature or proof data for that precompile.
How to identify it
- Read the TransactionError appended to the Agave error message and locate the corresponding precompile instruction.
How to resolve it
- Rebuild the precompile instruction with valid input data and signatures, then rebuild and re-sign the transaction.
RPC#
The requested slot was skipped or is missing because the local ledger jumped to a newer snapshot.
Diagnose and resolve
Why it happens
- The cluster did not produce a block for the slot, or the node does not have that slot in its local ledger.
How to identify it
- The Agave error message identifies the slot as skipped or missing due to a snapshot jump.
How to resolve it
- Do not assume every slot has a block. Treat a genuinely skipped slot as absent; if historical availability is required, query an endpoint with the necessary retained data.
RPC#
The requested slot was skipped or is missing from long-term storage.
Diagnose and resolve
Why it happens
- No stored block is available for that slot, including when the slot was skipped.
How to identify it
- The error message names the slot and explicitly identifies long-term storage.
How to resolve it
- Verify the slot. A skipped slot has no block to recover; otherwise contact support if the endpoint is expected to retain it.
RPC#
Transaction history is not available from the RPC node.
Diagnose and resolve
Why it happens
- The node was started without the required transaction-history capability or does not retain the requested history.
How to identify it
- The response message is "Transaction history is not available from this node".
How to resolve it
- Use an endpoint with transaction history and sufficient retention for the requested data.
RPC#
The serialized transaction does not contain the number of signatures required by its message header.
Diagnose and resolve
Why it happens
- The transaction was serialized incompletely or its signature array does not match the required signer count.
How to identify it
- The response message is "Transaction signature length mismatch".
How to resolve it
- Rebuild and serialize the transaction with a maintained Solana SDK, ensuring every required signer signs the final message.
RPC#
Status for the requested block is not yet available.
Diagnose and resolve
Why it happens
- The requested slot has not reached the state needed by the RPC method.
How to identify it
- The Agave message includes the slot whose block status is not yet available.
How to resolve it
- Wait for the required commitment and retry with bounded backoff.
RPC#
The response contains a transaction version newer than the maximum version declared by the request.
Diagnose and resolve
Why it happens
- The request omitted maxSupportedTransactionVersion or set it below the version named in the error message.
How to identify it
- Read the transaction version from the error message; do not assume it is always version 0.
How to resolve it
- If the application can decode that version, repeat the request with maxSupportedTransactionVersion set to at least the reported version. Otherwise upgrade the client first.
RPC#
The RPC node has not reached the minimum context slot required by the request.
Diagnose and resolve
Why it happens
- minContextSlot is greater than the node current context slot.
How to identify it
- Compare the requested minContextSlot with error.data.contextSlot, which reports the node current context.
How to resolve it
- Wait until the node reaches the required slot and retry. Lower minContextSlot only when doing so still satisfies the application consistency requirement.
RPC#
The method does not exist or is not available on the selected endpoint.
Diagnose and resolve
Why it happens
- A misspelled or case-mismatched method name, an unsupported method, or an add-on method that is not enabled.
How to identify it
- Inspect the exact case-sensitive method string and confirm it is supported by the endpoint.
How to resolve it
- Use the documented method name and enable any required add-on.
RPC#
The method exists, but one or more parameters are invalid.
Diagnose and resolve
Why it happens
- Wrong parameter count, order, type, encoding, public key, commitment, or configuration value.
How to identify it
- Read the validation message and compare the exact serialized params with the method reference.
How to resolve it
- Correct the invalid parameter rather than retrying the unchanged request.
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.
Solana RPC Error Code Example
This response was reproduced with an invalid public-key parameter. Error messages can contain more detail for other invalid parameters.
{
"jsonrpc": "2.0",
"error": {
"code": -32602,
"message": "Invalid param: Invalid"
},
"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