Error handling

Handle rejected request promises with try / catch. Streaming clients also report failures through the exception event.

Failure	Where to handle it
An HTTP request or top-level API rejection	Catch the request promise.
A WebSocket request failure	Catch the request promise; observe connection events as well.
A subscription or connection failure	Catch subscribe() failures and listen for exception.
An individual rejected order	Inspect each entry in the successful action response.

HTTP requests

RestClient throws HyperliquidApiError for HTTP transport failures and top-level Hyperliquid responses with status: 'err'.

import { HyperliquidApiError, RestClient } from '@siebly/hyperliquid-api';

async function main() {
  const client = new RestClient();

  try {
    const mids = await client.getAllMids();
    console.log(mids.BTC);
  } catch (error) {
    if (error instanceof HyperliquidApiError) {
      console.error(error.message);
      console.error('HTTP status:', error.status);
      console.error('Transport code:', error.code);
      return;
    }
    throw error;
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Property	Meaning
message	The error message from the API or HTTP client.
status	HTTP status, if a response was received. An API error can still have HTTP status 200.
code	Transport error code, when supplied by the HTTP client.
response	Response body, when available.
cause	Original error, when available.

Configuration and input errors can use other types, so keep a fallback in the error handler. HTTP requests are not retried automatically.

HyperliquidApiError reference

WebSocket requests and subscriptions

HyperliquidWebSocketError represents transport and protocol failures, including connection errors, request timeouts and error responses to WebSocket POST requests. An Exchange action response with status: 'err' instead rejects with HyperliquidApiError. Catch both types when using WebsocketAPIClient, and register an exception listener for connection and protocol events.

Handle rejected subscribe() promises and subsequent exception events. The server acknowledges subscriptions through response. The subscription example shows the handlers.

Reconnection restores subscriptions without replaying requests. After a timeout or disconnect during an action, check its outcome before resubmitting.

HyperliquidWebSocketError reference · WebsocketExceptionEvent

Order results

A successful request can contain rejected individual orders. Inspect each entry in response.data.statuses returned by submitOrder(): an entry can be resting, filled or error.

submitOrder() · OrderResponseData