Error Handling

Handle trading errors with PerpsError, error codes and per-action results

Trading calls report failure through two channels. Handle both. HTTP status, action status and error cause are three separate axes: see Execution reports.

Channel	What it covers	How it surfaces
Thrown PerpsError	Transport failures, request validation, signing failures, an unregistered provider, HTTP error statuses such as 401 / 2012	The call rejects with a PerpsError carrying a numeric code
Per-action result	A step that the venue refused or did not answer clearly, inside a successful 202 response	The call resolves; results[i].status is Failed or Indeterminate, with error and an optional errorCode

​

Thrown errors

Use PerpsErrorCode for type-safe handling:

import {
  OrderSide,
  OrderType,
  PerpsError,
  PerpsErrorCode,
  PerpsErrorMessage,
  isAbortError,
} from '@lifi/perps-sdk';

try {
  await perps.placeOrder({
    address: userAddress,
    provider: 'hyperliquid',
    market: { marketId: 'BTC', categoryId: 'hyperliquid' },
    side: OrderSide.BUY,
    type: OrderType.MARKET,
    size: '0.1',
    price: '95500.00',
  });
} catch (error) {
  // Aborted requests reject with the raw AbortError, not PerpsError.
  if (!isAbortError(error) && error instanceof PerpsError) {
    switch (error.code) {
      case PerpsErrorCode.TermsNotAccepted:    // 2012
        console.error('Accept the current terms first.');
        break;
      case PerpsErrorCode.MarketNotFound:      // 2023
        console.error('Market not found. Check getMarkets() for valid market ids.');
        break;
      case PerpsErrorCode.SDKError:            // 2005
        if (error.message === PerpsErrorMessage.AgentNotFound) {
          console.error('Agent key missing. Re-run provider setup.');
        }
        break;
      case PerpsErrorCode.NonceExpired:        // 2042
        console.error('Payload expired. Retry the operation.');
        break;
      default:
        console.error(`Error ${error.code}: ${error.message}`);
    }
  }
}

​

Terms must be accepted first

Every non-meta createAction and executeAction call fails with HTTP 401 and code 2012 (TermsNotAccepted) until the address has accepted the current terms version. That covers checkSetup (once the venue account exists), every setup step, trading and withdrawals. A terms-version bump gates the address again, including actions staged earlier.

Check and accept before any provider action:

import { getTermsAcceptance } from '@lifi/perps-sdk';

const terms = await getTermsAcceptance(perps.client, userAddress);
if (!terms.accepted) {
  await perps.submitOnboarding({
    address: userAddress,
    termsVersion: terms.termsVersion,
  });
}

​

Step results inside a successful response

A venue refusal (insufficient margin, invalid parameters, market closed) and an unclear venue answer both come back inside a 202 response. placeOrder, placeTriggerOrder, placeTwapOrder, cancelOrders, modifyOrders, cancelTwapOrder, updatePositionMargin, sendAsset, withdraw, execute, executeProviderSetupAction, executeProviderOption, executeProviderRevoke and the meta methods resolve with { results } and do not throw on it. 202 does not mean that the venue accepted a step. Read the status of every result:

status	Meaning	What to do
Submitted	The venue acknowledged the send. The acknowledgement is not proof.	Treat the step as sent. Track the outcome with Order Status.
Accepted	The venue provably applied the step. Ondo can return it in the response.	Treat the step as applied.
Indeterminate	The send started and the venue gave no clear answer: a timeout, a transport failure, a 5xx answer, or an answer that the backend cannot read. The step can have taken effect.	Read the account state. Do not submit the action again until you know the result.
Failed	The venue refused the step, or a check failed before the backend sent it. Nothing was applied.	Read errorCode and error. Correct the request.

The report holds only the steps that the backend attempted. It stops at the first Failed or Indeterminate step. Earlier acknowledgements stay in the report. Every member of an attempted atomic batch has a result, and two steps with the same action keep two results. This example handles every result:

import {
  OrderSide,
  OrderType,
  PerpsErrorCode,
  UserActionStatus,
} from '@lifi/perps-sdk';

const { results } = await perps.placeOrder({
  address: userAddress,
  provider: 'hyperliquid',
  market: { marketId: 'BTC', categoryId: 'hyperliquid' },
  side: OrderSide.BUY,
  type: OrderType.MARKET,
  size: '0.1',
  price: '95500.00',
});

for (const result of results) {
  switch (result.status) {
    case UserActionStatus.Submitted:
    case UserActionStatus.Accepted:
      console.log(`${result.action} acknowledged`, result.orderId);
      break;
    case UserActionStatus.Indeterminate:
      // The text of result.error ends with the advice to check the account.
      console.warn(result.error);
      break;
    case UserActionStatus.Failed:
      switch (result.errorCode) {
        case PerpsErrorCode.InsufficientMargin:  // 2021
          console.error('Not enough margin. Reduce size or add funds.');
          break;
        case PerpsErrorCode.InsufficientBalance: // 2022
          console.error('Insufficient balance. Deposit more funds.');
          break;
        default:
          // errorCode is optional; ExchangeRejected (2020) is the general venue rejection
          console.error(result.error);
      }
      break;
  }
}

ActionResult is one flat type. error is set unless the status is Submitted or Accepted, and errorCode is set when the cause is classified. orderId, twapId, txHash and explorerLink are set when the venue and the provider give them.

​

Returned result or thrown error

• A returned Failed result is a confirmed refusal of one step, with the steps before it kept in the report. A Failed result after verification can also come from a step that the backend first reported as Submitted or Indeterminate. The response that you hold does not show that change.
• A thrown PerpsError is a request, signing or transport failure with no report from the backend. Nothing in your hands says what the venue did.
• A thrown PerpsExecutionError means that a later stage failed after some results were known. Its response.results holds every known result, and cause holds the original error. Read the results before you handle the error.

Not every SDK execution throws the first failed step. The execution methods above return the report and leave the decision to you. A failed result in the report is an input to your code, not an exception.

​

SDK-originated messages

PerpsErrorMessage pairs canonical human-readable text with PerpsErrors the SDK itself raises (not the backend’s error responses): AgentNotFound (agent-signing setup incomplete) and AgentStorageCorrupt (a stored agent keypair is malformed and the agent must be revoked and re-approved). Both are thrown as PerpsErrorCode.SDKError (2005), so compare error.message.

​

Common Trading Errors

Code	Name	Cause
2012	TermsNotAccepted	The address has not accepted the current terms version
2021	InsufficientMargin	Not enough margin for order size/leverage
2022	InsufficientBalance	Account lacks funds
2020	ExchangeRejected	Venue rejected the action (invalid params, market closed)
2003	TimeoutError	The send did not get an answer. The result is Indeterminate.
2023	MarketNotFound	Unknown market id
2024	OrderNotFound	Order ID doesn’t exist or already filled
2042	NonceExpired	Payload TTL exceeded — retry operation

See Error Codes for the complete reference, including how errorCodeFromStatus resolves a code from an HTTP status.