> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onebalance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Learn more about error codes and how to resolve them.

Errors in OneBalance fall into two categories:

* **[Quote errors](#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](#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

<Info>
  See also: [EIP-7702 delegation FAQ](/faq/signing#what-happens-if-my-wallet-already-has-an-eip-7702-delegation-to-another-contract) for more background on this behavior.
</Info>

## 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

```typescript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Get Execution Status V3" icon="history" href="/api-reference/status/get-quote-status-v3">
    Check quote execution status with multi-chain support and retrieve failReason codes
  </Card>

  <Card title="Refund Reasons Guide" icon="book-open" href="/guides/quotes/refund-reasons">
    Detailed explanations and handling strategies for each fail reason
  </Card>
</CardGroup>