Enhanced Error Handling: FailReason Field for Refunded Quotes

​

What’s New

​

New Response Field

• failReason: Specific reason for the refund (e.g., “SLIPPAGE”, “INSUFFICIENT_BALANCE”)

{
  "quoteId": "0xfa6094cd...",
  "status": "REFUNDED",
  "user": "0x9b747cC14...",
  "recipientAccountId": "eip155:1/0x9b747cC14...",
  "failReason": "SLIPPAGE",
  "originChainOperations": [],
  "destinationChainOperations": []
}

​

Supported Fail Reasons

​

General Failure Reasons

• UNKNOWN: Unknown failure reason
• SLIPPAGE: Price moved beyond tolerance
• AMOUNT_TOO_LOW_TO_REFUND: Amount too low to refund
• DEPOSIT_ADDRESS_MISMATCH: Wrong deposit address
• DEPOSIT_CHAIN_MISMATCH: Wrong deposit chain
• INCORRECT_DEPOSIT_CURRENCY: Wrong currency deposited
• DOUBLE_SPEND: Double spend detected
• SOLVER_CAPACITY_EXCEEDED: System capacity exceeded
• DEPOSITED_AMOUNT_TOO_LOW_TO_FILL: Amount too low to fill
• NEGATIVE_NEW_AMOUNT_AFTER_FEES: Negative amount after fees
• NO_QUOTES: No quotes available
• MISSING_REVERT_DATA: Missing transaction revert data
• REVERSE_SWAP_FAILED: Reverse swap failed
• GENERATE_SWAP_FAILED: Swap generation failed
• TOO_LITTLE_RECEIVED: Output amount too low
• EXECUTION_REVERTED: On-chain execution reverted
• NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE: Higher rent fee required
• TRANSACTION_REVERTED: Transaction reverted
• ORIGIN_CURRENCY_MISMATCH: Source currency mismatch
• NO_INTERNAL_SWAP_ROUTES_FOUND: No valid swap routes
• SWAP_USES_TOO_MUCH_GAS: Gas limit exceeded
• INSUFFICIENT_FUNDS_FOR_RENT: Insufficient SOL for rent

​

Execution Revert Reasons

• ORDER_EXPIRED: Order validity expired
• ORDER_IS_CANCELLED: Order was cancelled
• TRANSFER_FROM_FAILED: Token transfer from failed
• TRANSFER_FAILED: Token transfer failed
• SIGNATURE_EXPIRED: Signature no longer valid
• INVALID_SIGNATURE: Malformed signature
• INSUFFICIENT_NATIVE_TOKENS_SUPPLIED: Not enough gas tokens
• TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE: Insufficient token approval
• TRANSFER_AMOUNT_EXCEEDS_BALANCE: Insufficient token balance
• INVALID_SENDER: Unauthorized sender
• ACCOUNT_ABSTRACTION_INVALID_NONCE: Smart wallet nonce error
• ACCOUNT_ABSTRACTION_SIGNATURE_ERROR: Smart wallet signature error
• TOKEN_NOT_TRANSFERABLE: Token has transfer restrictions
• ZERO_SELL_AMOUNT: Cannot sell zero tokens
• MINT_NOT_ACTIVE: Token minting disabled
• INCORRECT_PAYMENT: Wrong payment amount/method
• INVALID_GAS_PRICE: Gas price out of range

​

Platform-Specific Reasons

• JUPITER_INVALID_TOKEN_ACCOUNT: Solana token account issue
• SEAPORT_INEXACT_FRACTION: NFT marketplace fraction error
• SEAPORT_INVALID_FULFILLER: Unauthorized NFT order fulfiller
• ERC_1155_TOO_MANY_REQUESTED: Too many NFTs requested
• FLUID_DEX_ERROR: Fluid DEX protocol error
• ORDER_ALREADY_FILLED: Order previously completed

​

Integration Impact

• Backward Compatible: Existing integrations continue to work
• Optional Field: failReason only appears when status is REFUNDED
• Better Debugging: Developers can programmatically handle different refund scenarios
• Enhanced UX: Users receive specific, actionable feedback about failures

​

Example Usage

const status = await getExecutionStatus(quoteId);

if (status.status === 'REFUNDED' && status.failReason) {
  switch (status.failReason) {
    case 'SLIPPAGE':
      // Retry with fresh quote
      showRetryOption('Price changed during execution');
      break;
    case 'TRANSFER_AMOUNT_EXCEEDS_BALANCE':
      // Check balance
      showBalanceError('Insufficient token balance');
      break;
    case 'TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE':
      // Increase token allowance
      showAllowanceError('Token approval needed');
      break;
    case 'ORDER_EXPIRED':
      // Generate new quote
      showRetryOption('Order expired, please try again');
      break;
    case 'NO_QUOTES':
      // No liquidity available
      showLiquidityError('No quotes available for this pair');
      break;
    default:
      showGenericError(`Quote failed: ${status.failReason}`);
  }
}

​

Learn More

• Error Codes - Complete list of fail reason codes with troubleshooting steps
• Refund Reasons Guide - Detailed explanations and handling strategies
• Error Handling - Complete guide to API error handling
• Get Execution Status - Updated endpoint documentation