Error Types

The Nexus SDK uses a structured error system with specific error codes for different failure scenarios. All SDK errors are instances of NexusError.

NexusError class

All SDK errors extend the NexusError class, providing consistent error structure and metadata.

name

string

required

Always 'NexusError'

code

ErrorCode

required

Specific error code from ERROR_CODES. See Error codes

message

string

required

Human-readable error message

data

NexusErrorData

Additional error context and details

Show properties

context

string

Where or why the error occurred

cause

unknown

Optional nested error that caused this error

details

Record<string, unknown>

Specific structured information about the error

Methods

toJSON()

() => object

Serialize error to JSON-compatible object for logging or transmissionReturns:

{
  name: string;
  code: ErrorCode;
  message: string;
  data?: NexusErrorData;
}

Basic error handling

import { NexusError, ERROR_CODES } from '@avail-project/nexus-core';

try {
  await sdk.bridge(params);
} catch (error) {
  if (error instanceof NexusError) {
    console.error('Error code:', error.code);
    console.error('Message:', error.message);
    
    if (error.data?.context) {
      console.error('Context:', error.data.context);
    }
    
    if (error.data?.details) {
      console.error('Details:', error.data.details);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Error codes

All error codes are available in the ERROR_CODES constant.

import { ERROR_CODES } from '@avail-project/nexus-core';

User action errors

Errors caused by user denials or cancellations.

USER_DENIED_INTENT

string

User rejected the intent in the intent hookUser action: None - user cancelled the operation

USER_DENIED_ALLOWANCE

string

User rejected token approval in the allowance hookUser action: None - user cancelled the operation

USER_DENIED_INTENT_SIGNATURE

string

User rejected the signature request for intentUser action: None - user cancelled the operation

USER_DENIED_SIWE_SIGNATURE

string

User rejected SIWE (Sign-In with Ethereum) signatureUser action: None - user cancelled the operation

Balance and fund errors

INSUFFICIENT_BALANCE

string

Not enough tokens for the requested operationUser action: Show current balance and suggest deposit or reduce amount

NO_BALANCE_FOR_ADDRESS

string

No balance found for the specified addressUser action: Verify the address is correct

Validation errors

INVALID_INPUT

string

Invalid parameters provided to SDK methodUser action: Check input values and types

INVALID_ADDRESS_LENGTH

string

Address has incorrect length (not 20 bytes)User action: Verify address format is valid

INVALID_VALUES_ALLOWANCE_HOOK

string

Invalid values passed to allow() in allowance hookUser action: Check allow() arguments

TOKEN_NOT_SUPPORTED

string

Requested token is not supported on the networkUser action: Use a supported token (ETH, USDC, USDT, USDM)

Initialization errors

SDK_NOT_INITIALIZED

string

SDK method called before initializationUser action: Call await sdk.initialize(provider) first

SDK_INIT_STATE_NOT_EXPECTED

string

SDK is in an unexpected initialization stateUser action: Re-initialize the SDK

WALLET_NOT_CONNECTED

string

No wallet is connectedUser action: Connect wallet before proceeding

CONNECT_ACCOUNT_FAILED

string

Failed to connect to wallet accountUser action: Retry wallet connection

Chain and network errors

CHAIN_NOT_FOUND

string

Specified chain ID is not found or supportedUser action: Use a supported chain ID

CHAIN_DATA_NOT_FOUND

string

Chain data is unavailableUser action: Check network connection and retry

VAULT_CONTRACT_NOT_FOUND

string

Vault contract not found for the specified chainUser action: Contact support

ENVIRONMENT_NOT_SUPPORTED

string

Environment is not supportedUser action: Use ‘mainnet’ or ‘testnet’

ENVIRONMENT_NOT_KNOWN

string

Unknown environment specifiedUser action: Check SDK configuration

Transaction errors

TRANSACTION_TIMEOUT

string

Transaction timed out waiting for confirmationUser action: Retry operation or check block explorer

TRANSACTION_REVERTED

string

Transaction was reverted by the blockchainUser action: Check contract state and parameters

TRANSACTION_CHECK_ERROR

string

Error occurred while checking transaction statusUser action: Retry status check

FETCH_GAS_PRICE_FAILED

string

Failed to fetch current gas priceUser action: Retry operation

Operation errors

SIMULATION_FAILED

string

Transaction simulation failedUser action: Check parameters and balances

QUOTE_FAILED

string

Failed to get quote for swap or bridgeUser action: Retry operation

SWAP_FAILED

string

Swap operation failedUser action: Retry or adjust swap parameters

REFUND_FAILED

string

Refund request failedUser action: Contact support with intent ID

REFUND_CHECK_ERROR

string

Error checking refund statusUser action: Retry status check

Intent and solver errors

LIQUIDITY_TIMEOUT

string

Solver liquidity timeout - no solver could fulfill the intentUser action: Retry later or reduce amount

RATES_CHANGED_BEYOND_TOLERANCE

string

Exchange rate moved too much since quoteUser action: Refresh quote and retry

RFF_FEE_EXPIRED

string

Request for funds fee has expiredUser action: Retry operation to get new quote

DESTINATION_REQUEST_HASH_NOT_FOUND

string

Destination request hash not foundUser action: Contact support

DESTINATION_SWEEP_ERROR

string

Error sweeping funds on destination chainUser action: Contact support

Allowance errors

SLIPPAGE_EXCEEDED_ALLOWANCE

string

Slippage exceeded the approved allowanceUser action: Increase allowance amount

ALLOWANCE_SETTING_ERROR

string

Error setting token allowanceUser action: Retry approval transaction

Other errors

INTERNAL_ERROR

string

Internal SDK errorUser action: Contact support with error details

UNKNOWN_SIGNATURE

string

Unknown signature type encounteredUser action: Contact support

ASSET_NOT_FOUND

string

Requested asset not foundUser action: Check token address and chain

COSMOS_ERROR

string

Error on Cosmos chainUser action: Check Cosmos configuration

UNIVERSE_NOT_SUPPORTED

string

Universe/chain type not supportedUser action: Use supported chain

FEE_GRANT_REQUESTED

string

Fee grant was requestedUser action: Contact support

Error handling patterns

Specific error handling

import { NexusError, ERROR_CODES } from '@avail-project/nexus-core';

try {
  await sdk.bridge(params);
} catch (error) {
  if (error instanceof NexusError) {
    switch (error.code) {
      case ERROR_CODES.INSUFFICIENT_BALANCE:
        showInsufficientBalanceUI(error.data?.details);
        break;
        
      case ERROR_CODES.USER_DENIED_INTENT:
      case ERROR_CODES.USER_DENIED_ALLOWANCE:
        // User cancelled - not an error to display
        console.log('User cancelled operation');
        break;
        
      case ERROR_CODES.TRANSACTION_TIMEOUT:
        showRetryOption(error.message);
        break;
        
      case ERROR_CODES.LIQUIDITY_TIMEOUT:
        showMessage('No liquidity available. Try again later.');
        break;
        
      default:
        showGenericError(error.message);
    }
  } else {
    // Non-Nexus error
    console.error('Unexpected error:', error);
  }
}

Error logging

try {
  await sdk.bridge(params);
} catch (error) {
  if (error instanceof NexusError) {
    // Log to error tracking service
    errorTracker.log({
      code: error.code,
      message: error.message,
      context: error.data?.context,
      details: error.data?.details,
      serialized: error.toJSON(),
    });
  }
}

User-friendly error messages

const ERROR_MESSAGES: Record<string, string> = {
  [ERROR_CODES.INSUFFICIENT_BALANCE]: 'You don\'t have enough tokens for this operation.',
  [ERROR_CODES.LIQUIDITY_TIMEOUT]: 'Unable to find liquidity. Please try again later.',
  [ERROR_CODES.TRANSACTION_TIMEOUT]: 'Transaction is taking longer than expected. Check the block explorer.',
  [ERROR_CODES.CHAIN_NOT_FOUND]: 'This chain is not supported.',
};

try {
  await sdk.bridge(params);
} catch (error) {
  if (error instanceof NexusError) {
    const userMessage = ERROR_MESSAGES[error.code] || error.message;
    showUserMessage(userMessage);
  }
}

Core API

Hooks & Events

Types

Utilities

NexusError class

Methods

Basic error handling

Error codes

User action errors

Balance and fund errors

Validation errors

Initialization errors

Chain and network errors

Transaction errors

Operation errors

Intent and solver errors

Allowance errors

Other errors

Error handling patterns

Specific error handling

Error logging

User-friendly error messages

Build docs developers (and LLMs) love

Core API

Hooks & Events

Types

Utilities

​NexusError class

​Methods

​Basic error handling

​Error codes

​User action errors

​Balance and fund errors

​Validation errors

​Initialization errors

​Chain and network errors

​Transaction errors

​Operation errors

​Intent and solver errors

​Allowance errors

​Other errors

​Error handling patterns

​Specific error handling

​Error logging

​User-friendly error messages

Build docs developers (and LLMs) love

NexusError class

Methods

Basic error handling

Error codes

User action errors

Balance and fund errors

Validation errors

Initialization errors

Chain and network errors

Transaction errors

Operation errors

Intent and solver errors

Allowance errors

Other errors

Error handling patterns

Specific error handling

Error logging

User-friendly error messages