Error Handling

Error Hierarchy

Error
├─ HyperliquidError (SDK)
│  ├─ TransportError
│  │  ├─ HttpRequestError
│  │  └─ WebSocketRequestError
│  ├─ ApiRequestError
│  └─ AbstractWalletError
└─ ValiError (valibot)

HyperliquidError

Base class for all SDK errors.

import { HyperliquidError } from "@nktkas/hyperliquid";

try {
  await client.order({ ... });
} catch (error) {
  if (error instanceof HyperliquidError) {
    // Any SDK error
  }
}

TransportError

Thrown when an error occurs at the transport level (network issues, timeouts).

HttpRequestError

Thrown when an HTTP request fails.

import { HttpRequestError } from "@nktkas/hyperliquid";

try {
  await client.allMids();
} catch (error) {
  if (error instanceof HttpRequestError) {
    console.log(error.response); // Response object
    console.log(error.body); // Response body text
  }
}

WebSocketRequestError

Thrown when a WebSocket request fails.

import { WebSocketRequestError } from "@nktkas/hyperliquid";

try {
  await client.allMids();
} catch (error) {
  if (error instanceof WebSocketRequestError) {
    console.log(error.message);
  }
}

ApiRequestError

Thrown when the Hyperliquid API returns an error response. Contains the full response for inspection.

import { ApiRequestError } from "@nktkas/hyperliquid";

try {
  await client.order({ ... });
} catch (error) {
  if (error instanceof ApiRequestError) {
    console.log(error.message);  // Extracted error message
    console.log(error.response); // Full API response
  }
}

Common API errors:

• "User or API Wallet 0x... does not exist" - invalid signer or signature

• "Insufficient margin to place order" - not enough balance

• "Price too far from oracle" - price outside allowed range

AbstractWalletError

Thrown when wallet operations fail (signing, getting address).

import { AbstractWalletError } from "@nktkas/hyperliquid";

try {
  await client.order({ ... });
} catch (error) {
  if (error instanceof AbstractWalletError) {
    console.log(error.message);
  }
}

Validation Errors

Request parameters are validated before sending. Invalid parameters throw ValiError from valibot.

import * as v from "valibot";

try {
  await client.order({
    orders: [{
      a: -1, // invalid: must be non-negative
      // ...
    }],
    grouping: "na",
  });
} catch (error) {
  if (error instanceof v.ValiError) {
    console.log(error.issues); // Validation issues
  }
}

Example: Comprehensive Error Handling

import {
  AbstractWalletError,
  ApiRequestError,
  HttpRequestError,
  HyperliquidError,
  WebSocketRequestError,
} from "@nktkas/hyperliquid";
import * as v from "valibot";

try {
  const result = await client.order({ ... });
} catch (error) {
  if (error instanceof v.ValiError) {
    // Invalid parameters (before request)
    console.error("Validation failed:", error.issues);
  } else if (error instanceof ApiRequestError) {
    // API returned an error
    console.error("API error:", error.message);
  } else if (error instanceof HttpRequestError) {
    // HTTP request failed
    console.error("HTTP error:", error.response?.status);
  } else if (error instanceof WebSocketRequestError) {
    // WebSocket request failed
    console.error("WebSocket error:", error.message);
  } else if (error instanceof AbstractWalletError) {
    // Wallet operation failed
    console.error("Wallet error:", error.message);
  } else if (error instanceof HyperliquidError) {
    // Other SDK error
    console.error("SDK error:", error.message);
  } else {
    // Unknown error
    throw error;
  }
}