Error Codes

Error codes, HTTP status codes, and troubleshooting guide

All API errors return a PerpsError with a numeric code, the originating tool (DEX), and a human-readable message.

{
  "code": 2021,
  "tool": "hyperliquid",
  "message": "Insufficient margin for order"
}

In the SDK, errors are wrapped in PerpsSDKError which carries the numeric error code:

import { PerpsSDKError, PerpsErrorCode } from '@lifi/perps-sdk';

try {
  await perps.placeOrder({ ... });
} catch (error) {
  if (error instanceof PerpsSDKError) {
    console.log(error.code);    // 2021
    console.log(error.message); // 'Insufficient margin for order'

    // Use named constants for readable error handling
    if (error.code === PerpsErrorCode.InsufficientMargin) {
      // Handle insufficient margin
    }
  }
}

Error Types

For more specific handling, the SDK exports specialized error classes and utilities to inspect the error chain:

import {
  PerpsSDKError,
  HTTPError,
  AgentError,
  findErrorType,
} from '@lifi/perps-sdk';

try {
  await perps.placeOrder({ ... });
} catch (error) {
  // HTTPError — API returned a non-2xx response
  const httpErr = findErrorType(error, HTTPError);
  if (httpErr) {
    console.log(httpErr.status);       // HTTP status code (e.g., 422)
    console.log(httpErr.responseBody); // Full API error: { code, tool, message }
  }

  // AgentError — agent not found or not authorized
  const agentErr = findErrorType(error, AgentError);
  if (agentErr) {
    // Re-run the authorization flow
  }
}

Class	When thrown	Useful fields
PerpsSDKError	Top-level wrapper for all SDK errors	code, message, cause
HTTPError	API returned a non-2xx response	status, url, responseBody
AgentError	Agent not found or not authorized for DEX	code, message
ServerError	Network failure or timeout	code, message
ValidationError	Client-side parameter validation failed	message

Error Code Ranges

Error codes use the 2000+ range to avoid collision with the main LI.FI API (which uses 1000+):

Range	Category	Description
2000-2009	Base errors	Server errors, validation, timeout
2010-2019	Auth errors	Signature and authorization failures
2020-2039	Trading errors	Order execution and market errors
2040-2049	Nonce errors	Nonce validation and expiry
2050-2059	Payload errors	Payload integrity failures
2060-2069	Routing errors	Invalid API routes

Error Code Reference

Base Errors (2000-2009)

Code	Name	HTTP	Description
2000	DefaultError	500	Unexpected server error
2001	ServerError	500	Internal server error
2002	ValidationError	400	Request validation failed
2003	TimeoutError	408	Request timeout
2004	ThirdPartyError	424	External service failure

Authentication Errors (2010-2019)

Code	Name	HTTP	Description
2010	SignatureInvalid	401	Signature verification failed
2011	AgentUnauthorized	403	Agent wallet not approved

Trading Errors (2020-2039)

Code	Name	HTTP	Description
2020	ExchangeRejected	422	DEX rejected the operation
2021	InsufficientMargin	422	Not enough margin for the order
2022	InsufficientBalance	422	Not enough balance
2023	MarketNotFound	404	Unknown market/symbol
2024	OrderNotFound	404	Order doesn’t exist
2025	PositionNotFound	404	Position doesn’t exist

Nonce Errors (2040-2049)

Code	Name	HTTP	Description
2040	InvalidNonce	400	Nonce validation failed
2041	NonceAlreadyUsed	409	Nonce already consumed
2042	NonceExpired	410	Nonce TTL exceeded

Payload Errors (2050-2059)

Code	Name	HTTP	Description
2050	PayloadMismatch	400	Signed payload doesn’t match stored

Routing Errors (2060-2069)

Code	Name	HTTP	Description
2060	RouteNotFound	404	Invalid API route / endpoint does not exist

SDK Error Code Constants

The SDK exports PerpsErrorCode for type-safe error handling:

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

// Base errors
PerpsErrorCode.DefaultError      // 2000
PerpsErrorCode.ServerError       // 2001
PerpsErrorCode.ValidationError   // 2002
PerpsErrorCode.TimeoutError      // 2003
PerpsErrorCode.ThirdPartyError   // 2004

// Auth errors
PerpsErrorCode.SignatureInvalid  // 2010
PerpsErrorCode.AgentUnauthorized // 2011

// Trading errors
PerpsErrorCode.ExchangeRejected    // 2020
PerpsErrorCode.InsufficientMargin  // 2021
PerpsErrorCode.InsufficientBalance // 2022
PerpsErrorCode.MarketNotFound      // 2023
PerpsErrorCode.OrderNotFound       // 2024
PerpsErrorCode.PositionNotFound    // 2025

// Nonce errors
PerpsErrorCode.InvalidNonce      // 2040
PerpsErrorCode.NonceAlreadyUsed  // 2041
PerpsErrorCode.NonceExpired      // 2042

// Payload errors
PerpsErrorCode.PayloadMismatch   // 2050

// Routing errors
PerpsErrorCode.RouteNotFound     // 2060

Troubleshooting

ExchangeRejected (2020)

The DEX backend rejected the request. Check:

• Order parameters are valid (size within limits, price within bounds)
• The market is active and not in maintenance
• Request body matches the expected schema

InsufficientMargin (2021)

Not enough margin for the requested order. Check:

• Account has sufficient USDC balance
• Existing positions don’t consume too much margin
• Reduce leverage or order size

InsufficientBalance (2022)

Account lacks funds for the operation. Check:

• Deposit sufficient funds to your DEX account
• Check balances with getAccount()

SignatureInvalid (2010)

The signature could not be verified. Check:

• The correct wallet/agent signed the typedData
• The typedData was not modified after creation
• The nonce has not expired (re-call createOrder or createAuthorization to get fresh data)

AgentUnauthorized (2011)

The agent wallet is not approved on the DEX. Check:

• The authorization flow completed successfully (both createAuthorization and submitAuthorization)
• The agent address matches what was authorized
• The authorization has not been revoked

MarketNotFound (2023)

The symbol doesn’t exist on the specified DEX. Check:

• Use getMarkets() to list valid symbols
• Symbol is case-sensitive (use BTC, not btc)
• The market hasn’t been delisted

OrderNotFound (2024)

The order ID doesn’t exist. Check:

• Use the correct orderId (from the submit response)
• The order may have already been fully filled or cancelled
• Verify the dex parameter matches where the order was placed

PositionNotFound (2025)

No position exists for the specified symbol. Check:

• Verify you have an open position for this symbol
• Use getAccount() to list current positions

InvalidNonce (2040)

The nonce in the request failed validation. Check:

• The typedData was not modified after creation
• Re-call the create endpoint to get fresh payloads

NonceAlreadyUsed (2041)

The nonce has already been consumed by a previous request. This typically happens when:

• Submitting the same signed payload twice
• Re-submitting after a successful operation

Solution: Call the create endpoint again to get new payloads with fresh nonces.

NonceExpired (2042)

The nonce has exceeded its time-to-live. Payloads expire after a short period for security. Check:

• Sign and submit payloads promptly after creation
• Re-call the create endpoint to get fresh payloads

PayloadMismatch (2050)

The signed payload doesn’t match what was stored server-side. This can happen if:

• The typedData was modified before signing
• A different payload was substituted

Solution: Use the exact typedData returned from the create endpoint without modification.

ThirdPartyError (2004)

An external service (typically the DEX) returned an error. Check:

• DEX may be experiencing issues
• Retry after a short delay
• Check DEX status pages for outages

TimeoutError (2003)

The request exceeded the timeout limit. Check:

• Network connectivity
• DEX may be experiencing high latency
• Retry the operation