Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/availproject/nexus-sdk/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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);
  }
}