Error Handling

Every exception is importable from typed_lighter and derives from typed_lighter.Error.

Error
├── NetworkError        connection failed, timed out, or dropped
├── ValidationError     a response did not match its declared type
├── LogicError          a client-side invariant was broken
└── ApiError            Lighter answered with an error
    ├── AuthError       missing or rejected credentials
    ├── BadRequest      invalid input, or a refused business rule
    └── RateLimited     throttled

How Lighter Errors Map

Lighter reports failures as a numeric code beside a message. An error the venue answered with (from the main API, the explorer or the deposit bridge) carries (code_or_status, message, payload) as its args:

• code_or_status: Lighter's business code when the venue answered with one, otherwise the HTTP status of the failed response. A WebSocket error frame with no numeric code carries its raw code value here instead: None when the frame has none, or the string it sent;
• message: the venue's explanation;
• payload: the full error body as received.

An error raised locally, before anything is sent (the table further down), carries only (message,), and so do NetworkError, ValidationError and LogicError. Read args by position only after checking its length, or catch by class and use str(error).

Since a business code and an HTTP status are both integers, use error_code(error) to tell them apart: it returns the Lighter business code for a venue business error (also on an HTTP 5xx whose body carries one), and None for an HTTP-status error, a WebSocket error frame with no numeric code, or anything raised locally.

Raised locally, before anything is sent:

The other L1-signable transactions are not checked locally: without an Ethereum key, transfer and approve_integrator are signed and sent with no L1 signature, which is fine where Lighter does not need one (a transfer between accounts of the same master account, an approval for an integrator of the same master account or with zero fees). Where it does, the venue answers 21504, which is also an AuthError.

Reading The Code

from typed_lighter import ApiError, Lighter, error_code

async with Lighter.new() as client:
  try:
    await client.tx.cancel_order(market_index=0, order_index=999)
  except ApiError as error:
    code = error_code(error)
    if code is not None:
      print('Lighter code', code, error.args[1])
    elif len(error.args) == 3:
      print('HTTP or code-less error', error.args[0], error.args[1])
    else:
      print('Raised locally:', error)

Transactions And Nonces

A transaction Lighter refused with a business code does not burn its nonce: when the error is a BadRequest, AuthError or RateLimited and error_code(error) is a code other than 21104, the client reuses the nonce for the next transaction on that key. In every other case the client refetches the key's nonce from Lighter before its next transaction: 21104 invalid nonce, any HTTP 5xx (even one whose body carries a code), a network error, timeout (including a WebSocket transaction with no reply within the client's 10-second timeout, a NetworkError) or cancellation, an error with no business code, a code outside the classified ranges (a plain ApiError), and a reply that fails validation (ValidationError). Except for 21104, those outcomes are unknown: the transaction may still have been accepted, so look it up (by client_order_index, or by the hash client.signer computes) before sending it again.

The same rules hold however the nonce was chosen: by the client's nonce manager, pinned with client.tx.*(nonce=...), or signed beforehand and submitted with client.tx.send or client.tx.batch (for the client's own account).

A 200 reply means Lighter accepted the transaction, not that it executed; a sequencer rejection after acceptance raises nothing. Check the account's orders or streams for the outcome (Place & Manage Orders).

Recommended Pattern

from typed_lighter import (
  ApiError,
  AuthError,
  BadRequest,
  Lighter,
  NetworkError,
  RateLimited,
  ValidationError,
)

async with Lighter.new() as client:
  try:
    await client.tx.cancel_all_orders({'mode': 'immediate'})
  except AuthError:
    ...  # fix credentials; do not retry blindly
  except RateLimited:
    ...  # back off, then retry
  except BadRequest:
    ...  # the request itself is wrong; retrying the same call will not help
  except ApiError:
    ...  # other venue errors
  except NetworkError:
    ...  # reads can be retried; streams need resubscribing
  except ValidationError:
    ...  # the response changed shape; log it, or pass validate=False

Every API, transaction and stream method takes validate=False to skip response validation for one call, and Lighter.new(validate=False) turns it off client-wide.