Error Codes - OneBalance Docs

Errors in OneBalance fall into two categories:

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

These errors are returned during quote generation. No quote is created - resolve the issue before retrying.

Error Code	Description
`DELEGATION-001`	Account has a pre-existing EIP-7702 delegation to a non-Kernel contract

`DELEGATION-001`

Description: Account has a pre-existing EIP-7702 delegation to a contract other than the Kernel v3.3 contract (0xd6CEDDe84be40893d153Be9d467CD6aD37875b28). What it means: OneBalance won’t override existing delegations for security reasons (prevents double-spend attacks). The account can’t be used until the conflicting delegation is removed. Recommended action:

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

See also: EIP-7702 delegation FAQ for more background on this behavior.

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

`AMOUNT_TOO_LOW_TO_REFUND`

Description: Amount is too low to process a refund. What it means: The refund amount is below the minimum threshold. Recommended action:

Increase transaction amount
Contact support for small amounts

`DEPOSIT_ADDRESS_MISMATCH`

Description: Deposit address does not match expected address. What it means: Funds were sent to an incorrect address. Recommended action:

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

`DEPOSIT_CHAIN_MISMATCH`

Description: Deposit chain does not match expected chain. What it means: Funds sent on wrong blockchain network. Recommended action:

Verify correct chain before sending
Ensure wallet connected to correct network

`INCORRECT_DEPOSIT_CURRENCY`

Description: Deposited currency is incorrect. What it means: Wrong token type was deposited. Recommended action:

Verify correct token type
Check token contract addresses

`DEPOSITED_AMOUNT_TOO_LOW_TO_FILL`

Description: Deposited amount is too low to fill the order. What it means: Deposited amount doesn’t meet minimum requirements. Recommended action:

Increase deposit amount
Check minimum order requirements

`NEGATIVE_NEW_AMOUNT_AFTER_FEES`

Description: Negative amount after deducting fees. What it means: Fees exceed the transaction amount. Recommended action:

Increase transaction amount
Review fee structure

`MISSING_REVERT_DATA`

Description: Missing revert data from transaction. What it means: Transaction failed without detailed error information. Recommended action:

Contact support with transaction details
Try transaction again

`REVERSE_SWAP_FAILED`

Description: Reverse swap operation failed. What it means: Attempt to reverse a swap transaction failed. Recommended action:

Contact support for manual intervention
Review transaction history

`GENERATE_SWAP_FAILED`

Description: Failed to generate swap. What it means: System couldn’t create a valid swap transaction. Recommended action:

Try with different parameters
Check token compatibility

`NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE`

Description: New calldata includes higher rent fee. What it means: Updated transaction requires higher fees than originally quoted. Recommended action:

Accept higher fee or cancel
Request fresh quote

`TRANSACTION_REVERTED`

Description: Transaction was reverted. What it means: Blockchain transaction failed and was reverted. Recommended action:

Check gas settings
Verify transaction parameters

`ORIGIN_CURRENCY_MISMATCH`

Description: Origin currency mismatch. What it means: Source currency doesn’t match expectations. Recommended action:

Verify correct source token
Check wallet token selection

`NO_INTERNAL_SWAP_ROUTES_FOUND`

Description: No internal swap routes found. What it means: Unable to find a valid path for the swap. Recommended action:

Try alternative token pairs
Check liquidity availability

`SWAP_USES_TOO_MUCH_GAS`

Description: Swap uses too much gas. What it means: Swap would exceed gas limits. Recommended action:

Simplify swap path
Split into smaller transactions

`ORDER_IS_CANCELLED`

Description: Order has been cancelled. What it means: Order was cancelled before execution. Recommended action:

Submit new order if needed
Check cancellation reason

`TRANSFER_FROM_FAILED`

Description: Transfer from operation failed. What it means: Unable to transfer tokens from source. Recommended action:

Check token allowances
Verify token balance

`TRANSFER_FAILED`

Description: Transfer operation failed. What it means: Token transfer could not be completed. Recommended action:

Check token compatibility
Verify recipient address

`SEAPORT_INEXACT_FRACTION`

Description: Seaport inexact fraction. What it means: NFT marketplace order has fraction issues. Recommended action:

Adjust order parameters
Use whole units

`SEAPORT_INVALID_FULFILLER`

Description: Seaport invalid fulfiller. What it means: Not authorized to fulfill this Seaport order. Recommended action:

Check fulfiller requirements
Verify permissions

`ERC_1155_TOO_MANY_REQUESTED`

Description: ERC-1155 too many requested. What it means: Exceeds maximum ERC-1155 tokens per transaction. Recommended action:

Reduce number of tokens
Split into multiple transactions

`INCORRECT_PAYMENT`

Description: Incorrect payment. What it means: Payment amount or method is wrong. Recommended action:

Verify payment amount
Check payment currency

`FLUID_DEX_ERROR`

Description: Fluid DEX error. What it means: Error specific to Fluid DEX protocol. Recommended action:

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

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 Errors

​DELEGATION-001

​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

​AMOUNT_TOO_LOW_TO_REFUND

​DEPOSIT_ADDRESS_MISMATCH

​DEPOSIT_CHAIN_MISMATCH

​INCORRECT_DEPOSIT_CURRENCY

​DEPOSITED_AMOUNT_TOO_LOW_TO_FILL

​NEGATIVE_NEW_AMOUNT_AFTER_FEES

​MISSING_REVERT_DATA

​REVERSE_SWAP_FAILED

​GENERATE_SWAP_FAILED

​NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE

​TRANSACTION_REVERTED

​ORIGIN_CURRENCY_MISMATCH

​NO_INTERNAL_SWAP_ROUTES_FOUND

​SWAP_USES_TOO_MUCH_GAS

​ORDER_IS_CANCELLED

​TRANSFER_FROM_FAILED

​TRANSFER_FAILED

​SEAPORT_INEXACT_FRACTION

​SEAPORT_INVALID_FULFILLER

​ERC_1155_TOO_MANY_REQUESTED

​INCORRECT_PAYMENT

​FLUID_DEX_ERROR

​Integration Example

​Best Practices

​Related Documentation

Get Execution Status V3

Refund Reasons Guide

Quote Errors

`DELEGATION-001`

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`

`AMOUNT_TOO_LOW_TO_REFUND`

`DEPOSIT_ADDRESS_MISMATCH`

`DEPOSIT_CHAIN_MISMATCH`

`INCORRECT_DEPOSIT_CURRENCY`

`DEPOSITED_AMOUNT_TOO_LOW_TO_FILL`

`NEGATIVE_NEW_AMOUNT_AFTER_FEES`

`MISSING_REVERT_DATA`

`REVERSE_SWAP_FAILED`

`GENERATE_SWAP_FAILED`

`NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE`

`TRANSACTION_REVERTED`

`ORIGIN_CURRENCY_MISMATCH`

`NO_INTERNAL_SWAP_ROUTES_FOUND`

`SWAP_USES_TOO_MUCH_GAS`

`ORDER_IS_CANCELLED`

`TRANSFER_FROM_FAILED`

`TRANSFER_FAILED`

`SEAPORT_INEXACT_FRACTION`

`SEAPORT_INVALID_FULFILLER`

`ERC_1155_TOO_MANY_REQUESTED`

`INCORRECT_PAYMENT`

`FLUID_DEX_ERROR`

Integration Example

Best Practices

Related Documentation