Error Handling

The client distinguishes between failure modes through explicit exception types.

Common Error Categories

• NetworkError: connection failures, timeouts, and transport errors
• AuthError: authentication or signing failures
• ApiError: the remote API returned an application-level error
• ValidationError: the response shape did not match the expected schema
• LogicError: incorrect local usage of the client, or a *_paged sweep that could not continue without losing entries

Pagination

Hyperliquid pages history by time, and its millisecond timestamps are not unique. The *_paged helpers therefore re-read the millisecond a page ends on and drop the overlap by position, so entries sharing a timestamp are never skipped at a page boundary.

A millisecond holding a whole page of entries cannot be read past, because the endpoint has no cursor finer than time. The helpers raise LogicError rather than skipping it:

from datetime import datetime, timezone
from typed_hyperliquid import Hyperliquid, LogicError

user = '0xYourAccountAddress'
start_time = datetime.fromtimestamp(0, tz=timezone.utc)

async with Hyperliquid.new(public=True) as client:
  try:
    async for page in client.info.user_fills_by_time_paged(user=user, start_time=start_time):
      ...
  except LogicError:
    # the sweep stopped rather than dropping entries; the message names the
    # timestamp to resume from if the loss is acceptable
    ...

Recommended Pattern

from typed_hyperliquid import ApiError, AuthError, NetworkError, ValidationError

try:
  ...
except ValidationError:
  ...
except AuthError:
  ...
except ApiError:
  ...
except NetworkError:
  ...

Operational Guidance

• retry transient network failures carefully
• do not blindly retry signing or authentication failures
• log validation failures because they often signal upstream API changes
• keep trading examples separate from harmless exchange actions like noop()