Error Reference

HTTP status codes, JSON-RPC errors, WebSocket close codes, and how to fix them.

HTTP Status Codes

Code	Error	Cause & Resolution
400	Invalid Request	Malformed JSON, missing `jsonrpc`/`method`/`id`, or batch size > 20.
401	Auth Failed	Invalid signature, clock drift (>30s), expired session, or malformed key. See troubleshooting below.
402	Insufficient Credits	Balance is zero. Deposit USDC to continue.
403	Forbidden	Tier restriction (`getProgramAccounts` requires Performance) or replayed nonce.
404	Not Found	Account not activated. Call `POST /account/activate` first.
429	Rate Limited	Exceeded your tier's request limit. Use `Retry-After` header and exponential backoff.
500	Internal Error	Server-side issue. Include `X-Request-Id` when contacting support.
502	Upstream Error	Solana node unreachable. Check `/health` endpoint.
503	Service Unavailable	Maintenance or overload. Check status page.

These appear inside a 200 OK response when the error originates from the Solana node.

Code	Error	Description
-32700	Parse Error	Invalid JSON in request body
-32601	Method Not Found	Unsupported or misspelled method name
-32602	Invalid Params	Wrong parameter types or format (e.g., expected base58 pubkey)
-32002	Simulation Failed	Transaction simulation failed (blockhash not found, insufficient funds, etc.)
-32005	Node Unhealthy	Solana node is behind or unresponsive
-32007	Timeout	Long-running operation exceeded timeout

Code	Reason	Resolution
1008	Policy Violation	Token expired — re-authenticate and reconnect
4001	Auth Failed	Invalid token — verify your authentication
4002	Insufficient Credits	Balance below 10 — deposit USDC and reconnect
4003	Rate Limited	Sending messages too fast — add delays between sends

Authentication failures are the most common issue. Check these in order:

Clock sync — your system time must be within ±30 seconds of UTC. Run ntpdate pool.ntp.org or check your NTP daemon.
Body hash — must be SHA-256 of the exact raw request body string. Even whitespace differences will cause failure.
Encoding — signature and public key must both be base58-encoded.
Payload format — v1: {timestamp}:{nonce}:{body_hash}. v2: {method}:{path}:{timestamp}:{nonce}:{body_hash}
v2 headers — if using auth v2, you must include X-Auth-Version: 2, X-Http-Method, and X-Http-Path

Deposits take ~30 seconds after Solana finalization
Must send from your registered wallet — deposits from other wallets won't be detected
USDC only — SOL and other tokens are not credited
Minimum deposit is 1 USDC
Manual confirmation: POST /account/confirm-deposit with {"txSignature": "YOUR_TX"}

Category	Timeout	Methods
Read — Light	5s	`getSlot`, `getBalance`, `getAccountInfo`
Read — Medium	15s	`getTransaction`, `simulateTransaction`
Read — Heavy	30s	`getProgramAccounts`, `getBlock`
Send	10s	`sendTransaction`, `sendBundle`

These methods return 403 Forbidden on Standard tier:

See Account Tiers to upgrade.