Solana gRPC & RPC error reference

Your gRPC client got `Status { code: Unavailable }` with `connection refused` (or `transport is closing`). The TCP handshake never completed — either you're hitting the wrong port, TLS is misconfigured, or the endpoint is genuinely down.

The TCP socket opened but TLS negotiation failed. Usually a stale root CA bundle inside a Docker image, a missing SNI extension, or a corporate MITM proxy intercepting and presenting its own certificate.

`Status { code: DeadlineExceeded }` means the RPC didn't produce a response within the deadline you (or the default) set. On a streaming subscribe this usually means the initial handshake took too long, or the client's deadline was accidentally set on the whole stream instead of the initial call.

`Status { code: ResourceExhausted }` means the server refused to serve your call because you hit a limit — concurrent streams, messages-per-second, or filter complexity. Unlike HTTP 429, this is a hard rejection: the stream is closed and must be reconnected, not retried on the same channel.

`Status { code: Cancelled }` on an active stream almost always means the TCP connection was closed by a middlebox (Kubernetes pod restart, load balancer, NAT timeout). It's not an error in the programmer sense — it's a normal event to handle with reconnect logic.

`Status { code: InvalidArgument }` is the server rejecting your SubscribeRequest before streaming starts. Almost always a malformed filter: base58-encoded where base64 expected, commitment level spelled wrong, or an empty filter group.

Your stream is processing slot N and then suddenly processes N+4 — three slots vanished. Either the Solana network genuinely skipped those slots (normal, happens several times per hour), or your consumer fell behind and the provider dropped messages to keep up.

Your client throws parsing errors on SubscribeUpdate messages even though the stream opened successfully. The provider server returns a proto your client doesn't understand — a new optional field, or a message type added after your client was generated.

Your RPC endpoint is lagging behind the tip of the chain. Symptoms: `getSlot` returns a number much lower than Solana Explorer, `getAccountInfo` returns stale data, `getLatestBlockhash` gives expired blockhashes. Usually a shared-endpoint issue.

You called `getProgramAccounts` or `getSignaturesForAddress` and got `method not supported on this plan`. These are archival methods — expensive queries that scan all accounts owned by a program or all historical signatures of a wallet. Every provider gates them behind paid or dedicated tiers.

Your RPC call got HTTP 429 with a Retry-After header. Either you blew through the per-second burst (50-200 rps on most shared providers), or you hit the daily quota for your plan.

Your transaction failed with `BlockhashNotFound`. You used a blockhash the validator that received your submit no longer has in its recent cache — either stale, or you got it from a different node in a load-balanced pool.

Your transaction was submitted but not included before its blockhash expired. Either the network is congested and the validator dropped your tx for lack of priority fee, or your submit path is slow enough that 150 slots elapsed between fetch and inclusion.

Your transaction created an account or ATA but didn't fund it above the rent-exempt minimum. Solana requires every account to pre-pay rent for two years — currently 890,880 lamports (~$0.03) for the smallest useful account.

`Status { code: Unauthenticated }` on a Yellowstone gRPC subscribe means the server didn't see a valid API key in the metadata. The single most common cause is attaching the key to the client's constructor but not to the individual streaming call.

Your free-trial API key was valid for 14 days and has expired. Streams will terminate with UNAUTHENTICATED and JSON-RPC calls will return 401. Upgrade to Sniper ($99/mo) or Pro ($249/mo) to keep the same key active.