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 information about how to resolve them.
Error CodeDescription
SLIPPAGEPrice moved beyond slippage tolerance
INSUFFICIENT_BALANCEUser lacks required token balance
TIMEOUTQuote execution timed out
GAS_TOO_LOWInsufficient gas for execution
EXECUTION_FAILEDOn-chain execution failed
INSUFFICIENT_LIQUIDITYNot enough liquidity available
REVERTEDTransaction was reverted
PRICE_IMPACT_TOO_HIGHPrice impact exceeded limits
INVALID_PATHSwap path unavailable
APPROVAL_FAILEDToken approval issues
NETWORK_CONGESTIONNetwork congestion caused failure
N/ANo specific reason provided

​
Error Code Details

​
SLIPPAGE

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. How to resolve:
  • Request 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

​
INSUFFICIENT_BALANCE

The user had insufficient token balance to complete the swap. What it means: The user’s wallet doesn’t have enough of the source token(s) to execute the swap as quoted. How to resolve:
  • Verify the user’s token balances before requesting quotes
  • Ensure the user hasn’t moved tokens after quote generation
  • Check if tokens are locked in other protocols or pending transactions

​
TIMEOUT

The quote execution timed out before completion. What it means: The quote wasn’t executed within the valid time window. How to resolve:
  • Request a new quote and execute it promptly
  • Check network congestion which might delay execution
  • Ensure the quote is executed before the expiration timestamp

​
GAS_TOO_LOW

Insufficient gas was provided for the transaction execution. What it means: The gas limit or gas price was too low to complete the on-chain operations. How to resolve:
  • Increase the gas limit for complex swaps
  • Check current network gas prices
  • For multi-step swaps, ensure adequate gas is allocated

​
EXECUTION_FAILED

The on-chain execution failed for an unspecified reason. What it means: The smart contract execution reverted during the swap. How to resolve:
  • Check if the tokens have special transfer restrictions
  • Verify token approvals are still valid
  • Review any custom contract interactions in the quote

​
INSUFFICIENT_LIQUIDITY

Liquidity was insufficient to complete the swap at the requested size. What it means: The liquidity pools lacked sufficient depth to execute the swap without excessive price impact or slippage. How to resolve:
  • Try a smaller swap amount to reduce liquidity requirements
  • Consider splitting large swaps into multiple smaller transactions
  • Look for alternative token routes with better liquidity
  • Wait for liquidity conditions to improve

​
REVERTED

The transaction was reverted by the blockchain network. What it means: The on-chain transaction failed and was reverted, often due to contract logic or token restrictions. How to resolve:
  • Check if the tokens have transfer restrictions or are paused
  • Verify that contract interactions are valid
  • Review token-specific requirements (e.g., whitelist, fees)
  • Ensure wallet has sufficient native tokens for gas fees

​
PRICE_IMPACT_TOO_HIGH

The price impact of the swap exceeded acceptable limits. What it means: The swap would cause excessive price movement in the liquidity pool, potentially resulting in unfavorable execution. How to resolve:
  • Reduce the swap amount to minimize price impact
  • Increase slippage tolerance with caution (understand the risks)
  • Split large swaps into smaller transactions over time
  • Consider using alternative routes with better liquidity

​
INVALID_PATH

The swap path was invalid or unavailable. What it means: No valid routing path could be found between the source and destination tokens. How to resolve:
  • Try alternative token pairs with established liquidity
  • Check if both tokens are actively traded
  • Consider intermediate tokens to create a valid path
  • Verify token addresses are correct and not deprecated

​
APPROVAL_FAILED

Token approval failed or was insufficient. What it means: The smart contract couldn’t access the user’s tokens due to approval issues. How to resolve:
  • Re-approve token spending allowances in your wallet
  • Check for pending approval transactions that need confirmation
  • Ensure wallet prompts are not being blocked
  • Verify the approval amount covers the swap amount plus any fees

​
NETWORK_CONGESTION

Network congestion caused the transaction to fail. What it means: High network activity resulted in mempool delays or transaction timeouts. How to resolve:
  • Retry the transaction when network conditions improve
  • Increase gas price to prioritize transaction processing
  • Monitor network status and wait for lower congestion periods
  • Consider using alternative networks if available

​
N/A

No specific reason was provided for the refund. What it means: The refund occurred but no detailed reason was available. How to resolve:
  • Contact support with the quote ID for investigation
  • Try generating and executing a new quote

​
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 'INSUFFICIENT_BALANCE':
      // Inform user about insufficient balance
      console.log('Insufficient balance for swap');
      break;
    case 'TIMEOUT':
      // Retry with new quote
      console.log('Quote timed out, generating new quote');
      break;
    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