Error Codes

OneBalance logs every successful or failed quote execution. While HTTP status codes indicate API request success/failure, quote executions can fail for business logic reasons even when the API request succeeds (returns 200). When a quote execution fails, it will be marked as REFUNDED and include a failReason field explaining why. These codes help you handle execution failures programmatically and provide appropriate feedback to users. Every refunded quote links to this list through its failReason field.

Quote Execution Failures

The following is a complete list of OneBalance fail reason codes, their descriptions, and recommended actions for resolution.

General Failure Reasons

Error Code	Description
`UNKNOWN`	Unknown failure reason
`SLIPPAGE`	Price moved beyond slippage tolerance
`AMOUNT_TOO_LOW_TO_REFUND`	Amount is too low to process a refund
`DEPOSIT_ADDRESS_MISMATCH`	Deposit address does not match expected address
`DEPOSIT_CHAIN_MISMATCH`	Deposit chain does not match expected chain
`INCORRECT_DEPOSIT_CURRENCY`	Deposited currency is incorrect
`DOUBLE_SPEND`	Double spend detected
`SOLVER_CAPACITY_EXCEEDED`	Solver capacity has been exceeded
`DEPOSITED_AMOUNT_TOO_LOW_TO_FILL`	Deposited amount is too low to fill the order
`NEGATIVE_NEW_AMOUNT_AFTER_FEES`	Negative amount after deducting fees
`NO_QUOTES`	No quotes available
`MISSING_REVERT_DATA`	Missing revert data from transaction
`REVERSE_SWAP_FAILED`	Reverse swap operation failed
`GENERATE_SWAP_FAILED`	Failed to generate swap
`TOO_LITTLE_RECEIVED`	Received amount is too little
`EXECUTION_REVERTED`	Execution was reverted
`NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE`	New calldata includes higher rent fee
`TRANSACTION_REVERTED`	Transaction was reverted
`ORIGIN_CURRENCY_MISMATCH`	Origin currency mismatch
`NO_INTERNAL_SWAP_ROUTES_FOUND`	No internal swap routes found
`SWAP_USES_TOO_MUCH_GAS`	Swap uses too much gas
`INSUFFICIENT_FUNDS_FOR_RENT`	Insufficient funds for rent (Solana-specific)

Execution Revert Specific Reasons

Error Code	Description
`ORDER_EXPIRED`	Order has expired
`ORDER_IS_CANCELLED`	Order has been cancelled
`TRANSFER_FROM_FAILED`	Transfer from operation failed
`TRANSFER_FAILED`	Transfer operation failed
`SIGNATURE_EXPIRED`	Signature has expired
`INVALID_SIGNATURE`	Invalid signature provided
`INSUFFICIENT_NATIVE_TOKENS_SUPPLIED`	Insufficient native tokens supplied
`TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE`	Transfer amount exceeds allowance
`TRANSFER_AMOUNT_EXCEEDS_BALANCE`	Transfer amount exceeds balance
`INVALID_SENDER`	Invalid sender
`ACCOUNT_ABSTRACTION_INVALID_NONCE`	Account abstraction invalid nonce
`ACCOUNT_ABSTRACTION_SIGNATURE_ERROR`	Account abstraction signature error
`SEAPORT_INEXACT_FRACTION`	Seaport inexact fraction
`TOKEN_NOT_TRANSFERABLE`	Token is not transferable
`ZERO_SELL_AMOUNT`	Zero sell amount
`MINT_NOT_ACTIVE`	Mint is not active
`ERC_1155_TOO_MANY_REQUESTED`	ERC-1155 too many requested
`INCORRECT_PAYMENT`	Incorrect payment
`INVALID_GAS_PRICE`	Invalid gas price
`FLUID_DEX_ERROR`	Fluid DEX error
`ORDER_ALREADY_FILLED`	Order already filled
`SEAPORT_INVALID_FULFILLER`	Seaport invalid fulfiller

Jupiter Specific Failures

Error Code	Description
`JUPITER_INVALID_TOKEN_ACCOUNT`	Jupiter invalid token account (Solana)

Detailed Error Explanations

`SLIPPAGE`

Description: The swap failed because the price moved beyond the configured slippage tolerance. What it means: The market price of the tokens changed significantly between when the quote was generated and when it was executed, exceeding the maximum allowed price impact. Recommended action:

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`

Description: Transfer amount exceeds balance. What it means: Insufficient token balance for the transfer. Recommended action:

Check token balance
Reduce transfer amount

`TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE`

Description: Transfer amount exceeds allowance. What it means: Token approval is less than transfer amount. Recommended action:

Increase token allowance
Approve exact or unlimited amount

`ORDER_EXPIRED`

Description: Order has expired. What it means: The order validity period has passed. Recommended action:

Submit a new order
Execute orders more quickly

`INSUFFICIENT_NATIVE_TOKENS_SUPPLIED`

Description: Insufficient native tokens supplied. What it means: Not enough ETH/SOL/etc. for gas fees. Recommended action:

Add native tokens for gas
Check gas price estimates

`NO_QUOTES`

Description: No quotes available. What it means: Unable to find any valid quotes for the requested swap. Recommended action:

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

`EXECUTION_REVERTED`

Description: Execution was reverted. What it means: The on-chain execution failed and was reverted. Recommended action:

Check specific revert reasons below
Verify contract interactions

`INSUFFICIENT_FUNDS_FOR_RENT`

Description: Insufficient funds for rent. What it means: Not enough funds to cover rent fees (Solana-specific). Recommended action:

Add SOL for rent exemption
Maintain minimum balance requirements

`JUPITER_INVALID_TOKEN_ACCOUNT`

Description: Jupiter invalid token account. What it means: Token account issue on Jupiter (Solana). Recommended action:

Verify Solana token accounts
Initialize token account if needed

`UNKNOWN`

Description: Unknown failure reason. What it means: The failure reason could not be determined. Recommended action:

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

`DOUBLE_SPEND`

Description: Double spend detected. What it means: An attempt to spend the same funds twice was detected. Recommended action:

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

`SOLVER_CAPACITY_EXCEEDED`

Description: Solver capacity has been exceeded. What it means: The system’s solving capacity has been reached. Recommended action:

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

`TOO_LITTLE_RECEIVED`

Description: Received amount is too little. What it means: The output amount is below acceptable minimums. Recommended action:

Increase slippage tolerance
Try a different route or time

`INVALID_SIGNATURE`

Description: Invalid signature provided. What it means: The signature doesn’t match or is malformed. Recommended action:

Re-sign the transaction
Verify wallet connection

`SIGNATURE_EXPIRED`

Description: Signature has expired. What it means: The transaction signature is no longer valid. Recommended action:

Sign a new transaction
Execute signed transactions promptly

`INVALID_SENDER`

Description: Invalid sender. What it means: Transaction sender is not authorized. Recommended action:

Verify wallet connection
Check sender permissions

`ACCOUNT_ABSTRACTION_INVALID_NONCE`

Description: Account abstraction invalid nonce. What it means: Smart wallet nonce is incorrect. Recommended action:

Sync wallet state
Retry transaction

`ACCOUNT_ABSTRACTION_SIGNATURE_ERROR`

Description: Account abstraction signature error. What it means: Smart wallet signature validation failed. Recommended action:

Re-sign with correct wallet
Check wallet configuration

`TOKEN_NOT_TRANSFERABLE`

Description: Token is not transferable. What it means: Token has transfer restrictions. Recommended action:

Check token transfer rules
Verify token isn’t locked

`ZERO_SELL_AMOUNT`

Description: Zero sell amount. What it means: Attempting to sell zero tokens. Recommended action:

Specify a valid amount
Check input validation

`MINT_NOT_ACTIVE`

Description: Mint is not active. What it means: Token minting is currently disabled. Recommended action:

Wait for minting to activate
Check mint schedule

`ORDER_ALREADY_FILLED`

Description: Order already filled. What it means: Attempting to fill an already completed order. Recommended action:

Submit a new order
Check order status first

`INVALID_GAS_PRICE`

Description: Invalid gas price. What it means: Gas price is outside acceptable range. Recommended action:

Update gas price settings
Use current market rates

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

Get Execution Status V3

Check quote execution status with multi-chain support and retrieve failReason codes

Refund Reasons Guide

Detailed explanations and handling strategies for each fail reason

API Reference

EVM Operations

Multi-Chain Operations

Platform Data

Quote Execution Failures

General Failure Reasons

Execution Revert Specific Reasons

Jupiter Specific Failures

Detailed Error Explanations

`SLIPPAGE`

`TRANSFER_AMOUNT_EXCEEDS_BALANCE`

`TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE`

`ORDER_EXPIRED`

`INSUFFICIENT_NATIVE_TOKENS_SUPPLIED`

`NO_QUOTES`

`EXECUTION_REVERTED`

`INSUFFICIENT_FUNDS_FOR_RENT`

`JUPITER_INVALID_TOKEN_ACCOUNT`

`UNKNOWN`

`DOUBLE_SPEND`

`SOLVER_CAPACITY_EXCEEDED`

`TOO_LITTLE_RECEIVED`

`INVALID_SIGNATURE`

`SIGNATURE_EXPIRED`

`INVALID_SENDER`

`ACCOUNT_ABSTRACTION_INVALID_NONCE`

`ACCOUNT_ABSTRACTION_SIGNATURE_ERROR`

`TOKEN_NOT_TRANSFERABLE`

`ZERO_SELL_AMOUNT`

`MINT_NOT_ACTIVE`

`ORDER_ALREADY_FILLED`

`INVALID_GAS_PRICE`

Integration Example

Best Practices

Get Execution Status V3

Refund Reasons Guide

API Reference

EVM Operations

Multi-Chain Operations

Platform Data

​Quote Execution Failures

​General Failure Reasons

​Execution Revert Specific Reasons

​Jupiter Specific Failures

​Detailed Error Explanations

​SLIPPAGE

​TRANSFER_AMOUNT_EXCEEDS_BALANCE

​TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE

​ORDER_EXPIRED

​INSUFFICIENT_NATIVE_TOKENS_SUPPLIED

​NO_QUOTES

​EXECUTION_REVERTED

​INSUFFICIENT_FUNDS_FOR_RENT

​JUPITER_INVALID_TOKEN_ACCOUNT

​UNKNOWN

​DOUBLE_SPEND

​SOLVER_CAPACITY_EXCEEDED

​TOO_LITTLE_RECEIVED

​INVALID_SIGNATURE

​SIGNATURE_EXPIRED

​INVALID_SENDER

​ACCOUNT_ABSTRACTION_INVALID_NONCE

​ACCOUNT_ABSTRACTION_SIGNATURE_ERROR

​TOKEN_NOT_TRANSFERABLE

​ZERO_SELL_AMOUNT

​MINT_NOT_ACTIVE

​ORDER_ALREADY_FILLED

​INVALID_GAS_PRICE

​Integration Example

​Best Practices

​Related Documentation

Get Execution Status V3

Refund Reasons Guide

Quote Execution Failures

General Failure Reasons

Execution Revert Specific Reasons

Jupiter Specific Failures

Detailed Error Explanations

`SLIPPAGE`

`TRANSFER_AMOUNT_EXCEEDS_BALANCE`

`TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE`

`ORDER_EXPIRED`

`INSUFFICIENT_NATIVE_TOKENS_SUPPLIED`

`NO_QUOTES`

`EXECUTION_REVERTED`

`INSUFFICIENT_FUNDS_FOR_RENT`

`JUPITER_INVALID_TOKEN_ACCOUNT`

`UNKNOWN`

`DOUBLE_SPEND`

`SOLVER_CAPACITY_EXCEEDED`

`TOO_LITTLE_RECEIVED`

`INVALID_SIGNATURE`

`SIGNATURE_EXPIRED`

`INVALID_SENDER`

`ACCOUNT_ABSTRACTION_INVALID_NONCE`

`ACCOUNT_ABSTRACTION_SIGNATURE_ERROR`

`TOKEN_NOT_TRANSFERABLE`

`ZERO_SELL_AMOUNT`

`MINT_NOT_ACTIVE`

`ORDER_ALREADY_FILLED`

`INVALID_GAS_PRICE`

Integration Example

Best Practices

Related Documentation