healthy

Overview

Check the health and availability of the Aptos REST API node. This endpoint returns HTTP 200 when the node is operational and synced, making it ideal for monitoring, load balancing, and automated health checks in production environments.

Endpoint

GET /v1/-/healthy

Request

Path Parameters

None.

Query Parameters

None.

Request Body

None.

Response

Success Response (200)

Returns HTTP 200 with an empty or minimal response body when the node is healthy and ready to serve requests. The node is considered healthy when:

• The REST API service is running and responsive
• The underlying node is syncing or fully synced with the network
• Database connections are operational
• Critical system resources are available

Error Responses

Status	Error Code	Description
503	service_unavailable	Node is unhealthy, not synced, or starting up
500	internal_error	Critical error preventing normal operation

Any non-200 response indicates the node should not receive production traffic.

Code Examples

Shell script for monitoring:

curl -s -X GET -o /dev/null -w "%{http_code}\n" https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/-/healthy -H "Accept: application/json"

Python monitoring script:

import requests

def is_node_healthy(api_key):
    try:
        response = requests.get(
            f"https://api-aptos-mainnet.n.dwellir.com/{api_key}/v1/-/healthy",
            timeout=5
        )
        return response.status_code == 200
    except requests.exceptions.RequestException:
        return False

if is_node_healthy("YOUR_API_KEY"):
    print("Node is healthy")
else:
    print("Node is unhealthy")

TypeScript health check:

async function checkNodeHealth(apiKey: string): Promise<boolean> {
  try {
    const response = await fetch(
      `https://api-aptos-mainnet.n.dwellir.com/${apiKey}/v1/-/healthy`,
      { signal: AbortSignal.timeout(5000) }
    );
    return response.status === 200;
  } catch (error) {
    return false;
  }
}

Docker healthcheck in docker-compose.yml:

services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/-/healthy"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Use Cases

This endpoint is essential for production infrastructure:

1. Load Balancer Health Checks: Configure load balancers (AWS ALB, nginx, HAProxy) to use this endpoint for backend health checks, automatically routing traffic away from unhealthy nodes.

2. Kubernetes Readiness Probes: Set up Kubernetes readiness and liveness probes to ensure pods are only marked ready when the Aptos node is fully synced and operational.

3. Monitoring and Alerting: Integrate with monitoring systems (Prometheus, Datadog, New Relic) to track node availability and trigger alerts when health checks fail.

4. Automated Failover: Build high-availability systems that automatically switch to backup API endpoints when the primary node becomes unhealthy.

5. CI/CD Pipeline Gates: Use health checks in deployment pipelines to verify services are operational before promoting to production or completing rolling updates.

6. Service Discovery: Register nodes with service discovery systems (Consul, etcd) and use health checks to maintain an accurate registry of available endpoints.

Best Practices

Timeout Configuration: Set reasonable timeouts (3-5 seconds) for health check requests. If a node doesn't respond quickly, it's likely unhealthy and shouldn't serve traffic.

Check Frequency: Balance between responsiveness and load. For critical services, check every 10-30 seconds. For monitoring dashboards, 60 seconds is typically sufficient.

Retry Logic: Implement exponential backoff for retries. Don't immediately mark a node as unhealthy on a single failed check - wait for 2-3 consecutive failures.

Circuit Breaker Pattern: After detecting an unhealthy node, implement a circuit breaker that waits before rechecking. Avoid overwhelming an unhealthy node with continuous health checks.

Multiple Nodes: Never rely on a single node. Always maintain connections to multiple API endpoints and use health checks to select healthy ones dynamically.

Logging: Log health check failures with timestamps and status codes for troubleshooting and capacity planning.

Performance Considerations

Health check requests are extremely lightweight and typically complete in under 20ms. They don't touch the blockchain state layer - the node simply reports its operational status.

However, health checks do consume API rate limits and network resources. Avoid checking more frequently than every 5-10 seconds to prevent unnecessary load on shared infrastructure.

For Dwellir's managed API infrastructure, health checks are already performed internally at the load balancer level. The health endpoint is exposed primarily for client-side monitoring and verification purposes.

Integration with Other Endpoints

Combine health checks with the /v1 (ledger_info) endpoint for more detailed node status:

• /v1/-/healthy - Quick operational check (< 20ms)
• /v1 - Detailed sync status with version information (50-100ms)

Use /healthy for rapid health verification, then query /v1 for diagnostic information if health checks start failing.