RPC Errors Reference

Use this page when a Carbium RPC request fails and you need to decide which layer owns the problem: HTTP transport, API-key access, JSON-RPC request shape, Solana runtime behavior, or your client retry logic.

This is not a replacement for the full Solana RPC method reference. It is a production triage page for Carbium users who need the next correct check fast.

Part of the Carbium full-stack Solana infrastructure stack.

Start with the failure surface

The first split is simple: did the request fail at the HTTP layer, or did the JSON-RPC response include an error object?

What you see	Likely layer	First move
HTTP `401` or `403` before a JSON-RPC result	Auth, endpoint restriction, or plan access	Check the key, endpoint, and feature access
HTTP `429`	Throughput limit	Back off and inspect request bursts
HTTP `5xx`	Temporary service or upstream failure	Retry with backoff, then check status and usage patterns
JSON body with `error.code`	JSON-RPC request or Solana runtime	Read the code, message, and `error.data` before retrying
SDK exception with no HTTP code visible	Client wrapper	Log the raw response before changing infrastructure

Do not treat every failure as downtime. Most production incidents become easier to fix once you preserve the raw HTTP status, JSON-RPC error code, method name, parameters, and request time in one log line.

HTTP status codes

These failures happen before you can reason about the Solana method result.

HTTP status	What it usually means	What to check
`400`	The request could not be accepted as sent	Confirm the body is valid JSON and the request uses HTTP `POST`
`401`	Missing or invalid RPC key	Confirm `apiKey=YOUR_RPC_KEY` or the documented header is present
`403`	Access blocked by restriction or plan	Check allowed domains, allowed IPs, and gated features
`429`	Too many requests in a short window	Apply backoff and review traffic shape
`500`	Server-side failure	Retry after a short delay and keep the raw response
`503`	Temporary unavailability or overload	Retry with exponential backoff and check service health

For recurring 429 responses, use Solana RPC Rate Limits Explained. This page only tells you how to classify the failure; the rate-limit page owns burst mitigation and traffic-shaping guidance.

📘Solana's public RPC documentation also treats 429 as a rate-limit signal and 403 as blocked traffic. Carbium adds product-specific key, endpoint, plan, and dashboard context around those same operational signals.

JSON-RPC error codes

Solana RPC uses JSON-RPC 2.0 over HTTP POST. That means a request can return HTTP 200 and still contain an application-level error in the response body.

A typical JSON-RPC error looks like this:

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

Use the code to decide whether to fix the request, the method, or the runtime path:

Code	Standard meaning	Carbium user action
`-32700`	Parse error	Fix invalid JSON before changing endpoints
`-32600`	Invalid request	Confirm `jsonrpc`, `id`, `method`, and `params` are shaped correctly
`-32601`	Method not found	Check the method name and whether you are using a Solana HTTP method on the right surface
`-32602`	Invalid params	Compare your `params` array against the Solana method reference
`-32603`	Internal JSON-RPC error	Retry after a short delay and preserve the raw response for support
`-32000` to `-32099`	Server-defined error range	Read the message and `error.data`; do not collapse these into one generic retry path

If your SDK hides this structure, add a low-level request log while debugging. You need the actual error.code, error.message, and optional error.data to avoid guessing.

Request-shape mistakes

Many JSON-RPC errors are local request problems, not provider problems.

Solana HTTP methods expect:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "getSlot",
  "params": []
}

Common mistakes:

Mistake	Likely symptom	Fix
Sending `GET` instead of `POST`	HTTP failure or unsupported request	Use HTTP `POST` with `Content-Type: application/json`
Omitting `jsonrpc: "2.0"`	Invalid request	Include the JSON-RPC version field
Passing an object when the method expects an ordered array	`-32602 Invalid params`	Use the method-specific `params` format
Misspelling a method name	`-32601 Method not found`	Compare with the Solana RPC method list
Reusing Swap API headers against RPC or RPC URL auth against Swap API	Auth failure	Use the Carbium Auth Matrix

For a fast known-good test, start with getHealth or getSlot, then move to the method your app actually needs.

curl -X POST "https://rpc.carbium.io/?apiKey=$CARBIUM_RPC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getSlot",
    "params": []
  }'

Transaction and preflight errors

Transaction submission errors need a different response than read errors. A failed sendTransaction can mean the transaction was malformed, the blockhash expired, simulation failed, the signature was invalid, or the transaction was already accepted and your client lost track of the response.

When sendTransaction or preflight fails:

Preserve the full error.data object if it exists.
Check simulation logs before changing RPC providers.
Check getSignatureStatuses before resending a signed transaction.
Refresh the blockhash when the signing or approval path took too long.
Keep quote-build failures separate from RPC submission failures.

Solana's JSON structures document that sendTransaction preflight failures can return simulation-style detail inside error.data. That detail is often the most useful part of the response.

Symptom	Likely check
`Blockhash not found` or expired blockhash wording	Rebuild or refresh the transaction before sending again
Signature verification failure	Confirm the transaction was signed by the required signer for the current message
Simulation logs mention a program error	Debug the program instruction, accounts, slippage, or compute budget
No signature returned but the client timed out	Check `getSignatureStatuses` before resending
Swap API did not return a `txn`	Use Swap API Errors Reference, not RPC debugging

For transaction recovery patterns, use Blockhash Expiry Recovery Playbook and Sending Transactions through Carbium RPC.

Retry rules that avoid making incidents worse

Retries are useful only when they match the failure.

Failure	Retry?	Safer behavior
`401`	No	Fix key or endpoint configuration
`403`	No	Check restrictions or plan access
`429`	Yes, delayed	Exponential backoff with jitter; reduce concurrency
`500` / `503`	Yes, delayed	Backoff, preserve raw response, avoid retry storms
`-32602`	No	Fix method parameters
Transaction preflight failure	Usually no	Read logs and rebuild the transaction if needed
Network timeout after `sendTransaction`	Carefully	Check signature status before resending

For bots and high-throughput workers, centralize retry budgeting. Ten workers independently retrying the same failure can turn a small outage or rate-limit event into a self-inflicted traffic spike.

What to include when asking for support

Do not send secrets. Send enough context to reproduce the failure without exposing your key.

Include:

timestamp and timezone
Carbium product surface: RPC, gRPC, or Swap API
HTTP status code
JSON-RPC error.code and error.message
method name and redacted params
whether the request came from local, staging, or production
whether endpoint domain or IP restrictions are enabled
recent deploy, traffic spike, or retry-loop changes

Redact:

full API keys
full endpoint URLs that include apiKey=...
private wallet keys or seed phrases
customer identifiers that are not needed for debugging

🔶Need production Solana RPC with usage visibility and plan headroom? Start with Carbium at carbium.io, then use this page with monitoring and rate-limit docs when failures appear.