Error Codes

• Quote errors - returned during quote generation. The API responds with an error and no quote is created. Fix the issue and retry.
• Quote execution failures - happen after a quote is executed. The API request succeeds (returns 200), but the quote is marked as REFUNDED with a failReason field explaining why.

​

Quote Errors

​

DELEGATION-001

• Revoke the existing EIP-7702 delegation on the EOA, then retry. OneBalance will automatically delegate it to Kernel v3.3 on the next quote execution
• Alternatively, use a different EOA that has no pre-existing delegation

​

Quote Execution Failures

​

General Failure Reasons

​

Execution Revert Specific Reasons

​

Jupiter Specific Failures

​

Detailed Error Explanations

​

SLIPPAGE

• Try requesting a new quote with updated prices
• Consider increasing the slippage tolerance if appropriate for your use case
• For volatile assets, execute quotes more quickly after generation

​

TRANSFER_AMOUNT_EXCEEDS_BALANCE

• Check token balance
• Reduce transfer amount

​

TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE

• Increase token allowance
• Approve exact or unlimited amount

​

ORDER_EXPIRED

• Submit a new order
• Execute orders more quickly

​

INSUFFICIENT_NATIVE_TOKENS_SUPPLIED

• Add native tokens for gas
• Check gas price estimates

​

NO_QUOTES

• Try different token pairs
• Check if markets are available for the tokens
• Try again during active trading hours

​

EXECUTION_REVERTED

• Check specific revert reasons below
• Verify contract interactions

​

INSUFFICIENT_FUNDS_FOR_RENT

• Add SOL for rent exemption
• Maintain minimum balance requirements

​

JUPITER_INVALID_TOKEN_ACCOUNT

• Verify Solana token accounts
• Initialize token account if needed

​

UNKNOWN

• Contact support with the quote ID for investigation
• Try generating and executing a new quote

​

DOUBLE_SPEND

• Ensure transactions are properly sequenced
• Wait for transaction confirmation before initiating new ones

​

SOLVER_CAPACITY_EXCEEDED

• Try again after a short delay
• Consider splitting large orders into smaller ones

​

TOO_LITTLE_RECEIVED

• Increase slippage tolerance
• Try a different route or time

​

INVALID_SIGNATURE

• Re-sign the transaction
• Verify wallet connection

​

SIGNATURE_EXPIRED

• Sign a new transaction
• Execute signed transactions promptly

​

INVALID_SENDER

• Verify wallet connection
• Check sender permissions

​

ACCOUNT_ABSTRACTION_INVALID_NONCE

• Sync wallet state
• Retry transaction

​

ACCOUNT_ABSTRACTION_SIGNATURE_ERROR

• Re-sign with correct wallet
• Check wallet configuration

​

TOKEN_NOT_TRANSFERABLE

• Check token transfer rules
• Verify token isn’t locked

​

ZERO_SELL_AMOUNT

• Specify a valid amount
• Check input validation

​

MINT_NOT_ACTIVE

• Wait for minting to activate
• Check mint schedule

​

ORDER_ALREADY_FILLED

• Submit a new order
• Check order status first

​

INVALID_GAS_PRICE

• Update gas price settings
• Use current market rates

​

AMOUNT_TOO_LOW_TO_REFUND

• Increase transaction amount
• Contact support for small amounts

​

DEPOSIT_ADDRESS_MISMATCH

• Verify correct deposit address
• Contact support if funds sent to wrong address

​

DEPOSIT_CHAIN_MISMATCH

• Verify correct chain before sending
• Ensure wallet connected to correct network

​

INCORRECT_DEPOSIT_CURRENCY

• Verify correct token type
• Check token contract addresses

​

DEPOSITED_AMOUNT_TOO_LOW_TO_FILL

• Increase deposit amount
• Check minimum order requirements

​

NEGATIVE_NEW_AMOUNT_AFTER_FEES

• Increase transaction amount
• Review fee structure

​

MISSING_REVERT_DATA

• Contact support with transaction details
• Try transaction again

​

REVERSE_SWAP_FAILED

• Contact support for manual intervention
• Review transaction history

​

GENERATE_SWAP_FAILED

• Try with different parameters
• Check token compatibility

​

NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE

• Accept higher fee or cancel
• Request fresh quote

​

TRANSACTION_REVERTED

• Check gas settings
• Verify transaction parameters

​

ORIGIN_CURRENCY_MISMATCH

• Verify correct source token
• Check wallet token selection

​

NO_INTERNAL_SWAP_ROUTES_FOUND

• Try alternative token pairs
• Check liquidity availability

​

SWAP_USES_TOO_MUCH_GAS

• Simplify swap path
• Split into smaller transactions

​

ORDER_IS_CANCELLED

• Submit new order if needed
• Check cancellation reason

​

TRANSFER_FROM_FAILED

• Check token allowances
• Verify token balance

​

TRANSFER_FAILED

• Check token compatibility
• Verify recipient address

​

SEAPORT_INEXACT_FRACTION

• Adjust order parameters
• Use whole units

​

SEAPORT_INVALID_FULFILLER

• Check fulfiller requirements
• Verify permissions

​

ERC_1155_TOO_MANY_REQUESTED

• Reduce number of tokens
• Split into multiple transactions

​

INCORRECT_PAYMENT

• Verify payment amount
• Check payment currency

​

FLUID_DEX_ERROR

• Check Fluid DEX status
• Try alternative DEX

​

Integration Example

// Check execution status
const statusResponse = await fetch('/api/status/get-execution-status?quoteId=0x...', {
  headers: {
    'x-api-key': 'your-api-key'
  }
});

const status = await statusResponse.json();

if (status.status === 'REFUNDED' && status.failReason) {
  switch (status.failReason) {
    case 'SLIPPAGE':
      // Handle slippage - maybe retry with higher tolerance
      console.log('Quote refunded due to slippage');
      break;
    case 'TRANSFER_AMOUNT_EXCEEDS_BALANCE':
      // Inform user about insufficient balance
      console.log('Insufficient balance for swap');
      break;
    case 'TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE':
      // Need to increase token approval
      console.log('Token allowance insufficient');
      break;
    case 'ORDER_EXPIRED':
      // Order expired, need fresh quote
      console.log('Order expired, please request a new quote');
      break;
    case 'NO_QUOTES':
      // No quotes available for this pair
      console.log('No quotes available for this token pair');
      break;
    case 'EXECUTION_REVERTED':
      // Check for more specific revert reasons
      console.log('Transaction execution reverted');
      break;
    case 'UNKNOWN':
      // Unknown failure
      console.log('Unknown failure reason');
      break;
    // ... handle other cases
    default:
      console.log(`Quote refunded: ${status.failReason}`);
  }
}

​

Best Practices

• Always check the failReason: When a quote is refunded, use the failReason to provide appropriate feedback to users
• Implement retry logic: For certain fail reasons like SLIPPAGE or TIMEOUT, consider implementing automatic retry with adjusted parameters
• Monitor patterns: Track fail reasons to identify common issues and optimize your integration
• User communication: Translate technical fail reasons into user-friendly messages

​

Related Documentation