Error Reference

Errors come back in the standard JSON-RPC shape. The code tells you the category and the message usually names the exact problem:

{"jsonrpc":"2.0","error":{"code":-32404,"message":"IP not whitelisted"}}

Search this page for the message you got. If it is not here, the debugging guides at the bottom cover the wider problem.

Authentication errors

OrbitFlare checks access before your request reaches a Solana node. These errors come with an HTTP error status, and they look the same on HTTP and on the WebSocket handshake.

HTTP	Code	Message	Cause	Fix
401	`-32401`	`missing API key`	No key in the request	Send the key as `?api_key=YOUR_LICENSE_KEY` or in the `x-api-key` header
403	`-32402`	`invalid API key`	The key does not exist, or it was regenerated	Copy the current key from the dashboard
403	`-32404`	`IP not whitelisted`	The request came from an IP, or went to a region, that your license does not allow	Add the IP in the dashboard, or use a region your license includes
429			You went over your plan’s requests or transactions per second	Back off and retry, and spread bursts out. See rate limits
429		`archival rate limit exceeded`	You went over the archival limit, which is 10% of your plan’s RPS	Slow down archival calls such as `getTransactionsForAddress`. See archival requests

If a request works in one region and fails with -32404 in another from the same machine, the license does not include the second region. Check its allowed locations in the dashboard or with the locations endpoint.

Request errors

The request reached a Solana node, which rejected it. These come with HTTP 200, so check the body for error rather than relying on the status.

Code	Example message	Cause	Fix
`-32700`	`Parse error`	The body is not valid JSON	Check quoting and commas. With curl, wrap the JSON in single quotes
`-32601`	`Method not found`	The method name is wrong, or the method is not offered on this endpoint	Check the spelling against the method list. `voteSubscribe` does not exist since Alpenglow, and `blockSubscribe` is an add-on
`-32602`	`Invalid param: WrongSize`	An address or signature is not valid base58 of the right length	Check you passed the full address, not a label or a truncated copy
`-32602`	`invalid base58 encoding: InvalidCharacter`	A base64 transaction was sent without saying so	Add `{"encoding": "base64"}` to `sendTransaction` or `simulateTransaction`
`-32602`	`failed to deserialize ... VersionedTransaction`	The transaction bytes are incomplete or encoded twice	Serialize the signed transaction once and encode it once
`-32004`	`Block not available for slot 459760000`	The slot was skipped, or it is newer than what the node has	Skipped slots have no block. For new slots, retry after a moment
`-32015`	`Transaction version (1) is not supported by the requesting client`	The block or transaction contains a version 1 transaction and you allowed only version 0	Pass `"maxSupportedTransactionVersion": 1`
`-32016`	`Minimum context slot has not been reached`	You set `minContextSlot` higher than the node’s current slot	Lower it, or retry once the node catches up. `data.contextSlot` shows where the node is

About half of mainnet transactions now use version 1. Every call to getBlock, getTransaction or getTransactionsForAddress should pass "maxSupportedTransactionVersion": 1. getTransactionsForAddress does not return an error when you leave it out: it silently skips version 1 transactions, so the history you get back is incomplete.

Transaction errors

sendTransaction simulates every transaction before sending it, unless you turn that off with skipPreflight. A failed simulation comes back as -32002:

{
  "code": -32002,
  "message": "Transaction simulation failed: Blockhash not found",
  "data": { "err": "BlockhashNotFound", "logs": [], "unitsConsumed": 0 }
}

The text after Transaction simulation failed: is the reason. The most common ones:

Message	Fix
`Blockhash not found`	The blockhash expired or is from another cluster. Fetch a new one right before signing
`Attempt to debit an account but found no record of a prior credit.`	The fee payer has no SOL on this cluster. Fund it
`Error processing Instruction 0: custom program error: 0x1`	A program returned its own error. Read `data.logs`, then look up the code in that program’s error list

Transaction debugging explains how to read program errors and what to do when a transaction is accepted but never lands. Apex has its own errors, listed in Apex errors and rate limits.

WebSocket errors

Authentication failures happen during the handshake and return the authentication errors above as a plain HTTP response. Many WebSocket libraries only show the status code, so see WebSocket debugging for how to read the full message. Once connected, a bad request gets an error on the same socket:

Code	Message	Cause
`-32602`	`Invalid Request: Invalid pubkey provided`	The address in a subscription is not valid
`-32602`	`Invalid subscription id.`	Unsubscribing from an ID that does not exist on this connection, usually one from before a reconnect
`-32601`	`Method not found`	The subscription method is not available, or you sent a JSON-RPC `ping`, which Solana does not have

A connection closed with code 1006 and no reason was dropped, usually after sitting idle. Send WebSocket ping frames every 20 to 30 seconds.

gRPC errors

Jetstream and Yellowstone report problems as gRPC status codes. What a message means depends on your license’s authentication mode: in IP Whitelist mode access comes from a whitelisted IP, and in API Key Only mode from the license key in the x-token header.

Status	Message	Meaning
`Unauthenticated` (16)	`authentication required: provide x-token header`	Yellowstone: IP Whitelist mode, your IP is not whitelisted. API Key Only mode, no `x-token` was sent
`PermissionDenied` (7)	`IP not whitelisted for this api key`	Yellowstone: IP Whitelist mode, a valid key from an IP that is not whitelisted. API Key Only mode, the region is not on your license
`Unauthenticated` (16)	`invalid x-token: api key not found`	Yellowstone: the x-token is not a valid key
`Unavailable` (14)	`error reading from server: EOF` or `connection reset by peer`	Jetstream: IP Whitelist mode, your IP is not whitelisted. API Key Only mode, no valid `x-token`. If an endpoint isn’t covered by your license, hitting it results in this too. Also returned by `SubscribeParsed`, which is not implemented
`ResourceExhausted` (8)	`connection limit exceeded`	Your IP already has 50 gRPC connections open
	`tls: first record does not look like a TLS handshake`	You used TLS. Both services are plaintext, so use `http://`

gRPC debugging covers these in detail, along with filters that connect fine but return nothing.

Server errors

HTTP	Meaning	Fix
500	Unexpected error on our side	Retry after a short delay
502, 503, 504	The node behind the endpoint is restarting, overloaded or slow	Retry with exponential backoff, and fail over to another region if it continues

The SDKs retry these automatically with backoff, and fail over to any fallback URLs you configure.

Debugging guides

Transactions

Failed, rejected, or never landed.

WebSocket

Refused, silent, or dropping connections.

gRPC

Jetstream and Yellowstone access and filters.

Still stuck? Ask in Discord with the endpoint, the request and the full error.

Get Started

Troubleshooting

Agents

Products

Solutions

Fetching Data

DAS API

RPC

Data Streaming

Apex

Trading APIs

Authentication errors

Request errors

Transaction errors

WebSocket errors

gRPC errors

Server errors

Debugging guides

Transactions

WebSocket

gRPC

​Authentication errors

​Request errors

​Transaction errors

​WebSocket errors

​gRPC errors

​Server errors

​Debugging guides

Transactions

WebSocket

gRPC

Authentication errors

Request errors

Transaction errors

WebSocket errors

gRPC errors

Server errors

Debugging guides