Errors

Errors come from two places. The constant-k gateway checks your key and your limits before a request reaches a node, and answers with an HTTP error status such as 401 or 403. The Solana node runs the method and answers with a JSON-RPC error object.

{
  "jsonrpc": "2.0",
  "error": { "code": -32602, "message": "Invalid param: WrongSize" },
  "id": 1
}

Some errors also carry a data field with details, such as simulation logs.

Gateway errors

The gateway answers with a JSON-RPC error body and "id": null, except the getTokenLargestAccounts concurrency 429, which echoes the request id. Placeholders in angle brackets are filled in with the method, the category or the limit that was hit.

Long-term storage responses

On Blade Runner and Nexus tier plans, Cube Runner retrieves a block from long-term storage when no cache, ledger or other region holds it. A getBlock request returns the block when it is retrieved within 25 seconds. Otherwise the response is HTTP 429 with a Retry-After header and code -32019, and it echoes the request id.

Standard JSON-RPC errors

Solana node errors

These codes come from the node software, as do their messages.

Transaction version errors

getBlock, getTransaction and blockSubscribe take a maxSupportedTransactionVersion parameter that says which formats your client can decode. Two errors come from getting it wrong.

The ceiling is raised after the client can decode the format, not before. Transaction v1 has the full error bodies, the client minimums and the migration steps.

Transaction errors

When preflight is on, a failed simulation returns -32002 and the send is rejected. The data object holds the transaction error and the program logs:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32002,
    "message": "Transaction simulation failed: Error processing Instruction 2: custom program error: 0x1",
    "data": {
      "err": { "InstructionError": [2, { "Custom": 1 }] },
      "logs": ["Program 11111111111111111111111111111111 invoke [1]", "…"]
    }
  },
  "id": 1
}

With skipPreflight: true, the send succeeds even if the transaction would fail. getSignatureStatuses gives the result: a landed but failed transaction has a non-null err.

In @solana/kit, the error carries its own context:

import {
  createSolanaRpc,
  isSolanaError,
  SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
  SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR,
} from "@solana/kit";

const rpc = createSolanaRpc(
  `https://rpc-newyork.constant-k.com/?api-key=${process.env.CK_API_KEY}`,
);

// wireTx: a signed, base64-encoded transaction (see Sending Transactions)
try {
  await rpc.sendTransaction(wireTx, { encoding: "base64" }).send();
} catch (e) {
  if (isSolanaError(e, SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE)) {
    // Simulation failed: the logs usually say why
    console.error(e.context.logs);
    console.error(e.cause); // the transaction error
  } else if (isSolanaError(e, SOLANA_ERROR__RPC__TRANSPORT_HTTP_ERROR)) {
    // Rejected by the gateway, for example 401 or 403
    console.error("HTTP", e.context.statusCode);
  } else {
    throw e;
  }
}

WebSocket errors

A failed subscribe returns a JSON-RPC error frame with the codes above, for example -32602 for a bad address, and the connection stays open.

gRPC errors

These apply to Kaldera, Turbo Kaldera and ShredPrism.

Some clients report a failed login differently:

• @triton-one/yellowstone-grpc (TypeScript): failed to open subscribe stream.
• grpcurl and other grpc-go tools: unexpected HTTP status code received from server: 204 (No Content).
• yellowstone-grpc-client (Rust): code: 'The request does not have valid authentication credentials', message: "Missing or Invalid API Key".

When to retry

Backoff starts at about 250 ms, doubles each time, carries random jitter, and caps at a few seconds. A response with a Retry-After header sets the wait instead. WebSocket and gRPC streams use the same backoff, then resubscribe.