getHealth

Learn getHealth use cases, code examples, request parameters, response structure, and tips.

The getHealth RPC method is used to check the operational health of a Solana RPC node. A node is considered "healthy" if it is responsive and sufficiently synchronized with the cluster—typically within a configurable slot lag known as HEALTH_CHECK_SLOT_DISTANCE.

This method is essential for monitoring, load balancing, and infrastructure failover strategies.

---

⚙️ How It Works

The getHealth method is a standard JSON-RPC POST request. It queries the RPC node to determine whether it is healthy according to its local configuration and synchronization status with the cluster.

---

✅ Common Use Cases

• Node Health Monitoring Periodically check RPC node status to ensure it's up and not significantly behind the cluster tip.

• Load Balancer Integration Route traffic only to nodes reporting healthy status in a pool of RPC endpoints.

• Failover Systems Automatically switch to a backup node if the primary node becomes unhealthy or unreachable.

• Quick Connectivity Debugging Use for basic diagnostics when a node appears to be lagging or unresponsive.

---

🛠 Request Parameters

This method does not accept any parameters.

---

📦 Response Structure

The response varies based on node status:

Status	Description
"ok"	Node is healthy and in sync with the cluster.
"behind"	Node is lagging behind the cluster (not within HEALTH_CHECK_SLOT_DISTANCE).
"unknown"	Node cannot determine its health—often due to isolation or startup.
error object	Node is unhealthy or unresponsive. Exact structure may vary between providers.

Example Healthy Response:

jsonCopyEdit{
  "jsonrpc": "2.0",
  "result": "ok",
  "id": 1
}

---

💡 Example: Check Node Health Using cURL

curl -X POST https://rpc.coinvera.io/?x-api-key=your-coinvera-x-api-key \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getHealth"
  }'

---

Code Examples

Nodejs

const fetch = require('node-fetch');

async function getHealth(rpcUrl) {
  try {
    const response = await fetch(rpcUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method: 'getHealth',
      }),
    });

    const data = await response.json();
    
    // Print the exact full response
    console.log('Full RPC Response:');
    console.log(JSON.stringify(data, null, 2));
    
    return data;
  } catch (error) {
    console.error('Error getting health:', error.message);
    return null;
  }
}

// Example usage
const RPC_URL = 'https://rpc.coinvera.io/?x-api-key=your-coinvera-x-api-key';

getHealth(RPC_URL);

Python

Example Response

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "ok"
}

🧠 Developer Tips

• What Counts as “Healthy” A node is healthy if it is not behind the cluster tip by more than the configured HEALTH_CHECK_SLOT_DISTANCE. This setting varies by node configuration.

• "Behind" or "Unknown" States

  • "behind": The node is online but lagging. It may still serve some traffic depending on tolerance.

  • "unknown": The node cannot confirm its health—possibly isolated or still catching up.

• Provider Behavior May Vary Different RPC providers (like CoinVera or others) may implement health checks with subtle differences. Always test with your provider.

• Robust Error Handling Is Crucial Treat any non-"ok" response with appropriate fallback logic (e.g., retry, alert, failover).

• Complement with getSlot or getEpochInfo For advanced monitoring, combine getHealth with other RPCs to track slot lag, block production, or sync status.