Home Docs Telegram Status

Error Reference

Nodius returns errors via HTTP status codes and JSON-RPC error objects. This guide covers all error conditions, their meanings, and how to handle them.

HTTP Status Codes

200 OK

Request succeeded. The response body contains the JSON-RPC result. Note that a 200 status can still contain a JSON-RPC error (e.g., method not found) — always check the error field in the response.

400 Bad Request

The request body is malformed or missing required fields.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request body must be valid JSON"
  }
}

Common causes: - Invalid JSON syntax - Missing jsonrpc, method, or id fields - Invalid method parameters - Batch size exceeds maximum (20)

401 Unauthorized

Authentication failed.

{
  "error": {
    "code": "AUTH_FAILED",
    "message": "Invalid signature"
  }
}

Common causes: - Missing authentication headers - Invalid Ed25519 signature - Timestamp outside ±30 second window - Expired session token - Malformed public key

Troubleshooting: - Verify your system clock is synchronized (use NTP) - Ensure you're signing the correct payload format: solana-nodius:v2:{method}:{path}:{timestamp}:{nonce}:{body_hash}. - Check that the body hash matches the actual request body - Verify the signed path is the URL path only, without query string.

402 Payment Required

Insufficient credits.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32010,
    "message": "insufficient credits"
  }
}

Resolution: Deposit USDC to the shared deposit wallet. Check the wallet address via GET /account/info.

403 Forbidden

The request is authenticated but not authorized.

{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "method not allowed: requestAirdrop"
  }
}

Common causes: - Replayed nonce (same nonce used within 60-second window) - Calling a denied method (requestAirdrop) - Account suspended

{
  "error": {
    "code": "NONCE_REUSED",
    "message": "Nonce has already been used"
  }
}

404 Not Found

Account or resource not found.

{
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "No account found for pubkey. Activate one via POST /account/activate"
  }
}

429 Too Many Requests

Rate limit exceeded.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 1 second."
  }
}

Headers:

Retry-After: 1
X-Ratelimit-Limit: 50
X-Ratelimit-Remaining: 0
X-Ratelimit-Reset: 1712000001

Resolution: Wait for the duration specified in Retry-After before retrying. Implement exponential backoff for repeated 429s.

500 Internal Server Error

Something went wrong on the server.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "requestId": "req_abc123"
  }
}

Resolution: Retry with backoff. If the issue persists, contact support with the requestId.

502 Bad Gateway

The upstream Solana node is unreachable.

{
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Solana node unavailable"
  }
}

Resolution: Retry after a brief delay. Check /health for node status.

503 Service Unavailable

The service is temporarily unavailable. This can happen during startup, upstream failure, overload, accounting dependency failure, or critical disk pressure. Transient service-gate denials happen before billing and include a retry hint when available.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32003,
    "message": "hot_rpc service temporarily unavailable due to critical disk pressure"
  }
}

Resolution: Retry with exponential backoff. Check nodius.xyz/status.

JSON-RPC Error Codes

These errors are returned inside a 200 OK response, in the JSON-RPC error field. They originate from the Solana node or the proxy's JSON-RPC handling.

-32700: Parse Error

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error: invalid JSON"
  }
}

The request body is not valid JSON.

-32600: Invalid Request

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Invalid request: missing 'method' field"
  }
}

The JSON is valid but doesn't conform to the JSON-RPC 2.0 specification.

-32601: Method Not Found

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found: getInvalidMethod"
  }
}

The requested method is not supported. Check the API Reference for supported methods.

-32602: Invalid Params

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

Method parameters are invalid. Check the Solana JSON-RPC documentation for the correct parameter format.

-32603: Internal Error

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error"
  }
}

An unexpected error occurred in the RPC handler.

-32000 to -32099: Server Errors

Solana-specific server errors:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "Transaction simulation failed: Blockhash not found"
  }
}

Common Solana-specific errors:

Code Typical Message Description
-32001 Node is behind by X slots Node is not caught up
-32002 Transaction simulation failed Transaction would fail
-32003 Transaction signature verification failure Bad transaction signature
-32004 Block not available Requested block has been purged
-32005 Node is unhealthy Node health check failed
-32006 No snapshot available Snapshot not available
-32007 Long-running operation Request timed out on the node
-32009 Slot was skipped Requested slot has no block
-32010 Key excluded from secondary index Missing index entry
-32014 Minimum slot not reached Slot not yet reached
-32015 Unsupported transaction version Version incompatibility

Request Timeouts

Requests have method-dependent timeouts:

Category Timeout Examples
READ_CHEAP 5 seconds getSlot, getBalance, getAccountInfo
READ_MEDIUM 15 seconds getTransaction, simulateTransaction
READ_HEAVY / ARCHIVE 30 seconds Heavy indexed/archive endpoints when enabled
SEND 10 seconds sendTransaction
SEND_BUNDLE 10 seconds sendBundle

If a request exceeds its timeout, the proxy returns a 504 Gateway Timeout or a JSON-RPC error with code -32007.

WebSocket Error Codes

Close Codes

Code Reason Description
1000 normal Clean close by client
1008 policy_violation Invalid or expired token
4001 auth_failed WebSocket authentication failed
4002 insufficient_credits Credit balance below minimum (10)
4003 rate_limited Too many messages per second

Subscription Errors

Returned as JSON-RPC error messages on the WebSocket:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Subscription limit reached (10/10)"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "method not allowed: requestAirdrop"
  }
}

Common Troubleshooting

"Invalid signature" on every request

  1. Check your clock: Your system time must be within ±30 seconds of UTC. Run ntpdate or check your NTP configuration.
  2. Verify the signing payload: Use solana-nodius:v2:{method}:{path}:{timestamp}:{nonce}:{body_hash}. The body hash is SHA-256 of the raw request body string.
  3. Ensure you're signing with the correct key: The public key in X-Pubkey must correspond to the private key used for signing.
  4. Check encoding: The signature should be base58-encoded. The public key should be base58-encoded.
  5. Check the path: Sign the URL path only, without query string.

"Account not found" after creating keypair

You need to activate your public key with the service before making RPC calls:

await rpc.activate();

Or POST /account/activate with your signed request.

"Insufficient credits" but I sent a deposit

Rate limited despite low request volume

WebSocket keeps disconnecting

Service-gate error for archive or heavy indexed methods

The hot-node endpoint is optimized for low-latency bots. Archive/history methods such as getTransaction, getSignaturesForAddress, and getBlock, plus heavy indexed methods such as getProgramAccounts, are enabled on dedicated endpoint profiles. When a profile is disabled, the RPC response uses -32004 and no credits are consumed.

Requests timing out

Timeouts vary by method category:

If requests consistently time out, the Solana node may be under load — check /health.

Nodius — nodius.xyz · Telegram · Status