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

# Error Codes

> Complete reference of all 46 error codes in the LeoKit API with scenarios and solutions

## Overview

This reference provides a complete catalog of all error types returned by the LeoKit API, organized by category with HTTP status codes, scenarios, and solutions.

## Validation Errors (HTTP 400)

### BAD\_REQUEST

**Message:** "Invalid request. Please check your inputs and try again."

**Scenarios:**

* Malformed JSON in request body
* Invalid parameter types
* Missing required fields

**Example Response:**

```json theme={null}
{
  "error": "Invalid request. Please check your inputs and try again.",
  "status": 400,
  "code": "BAD_REQUEST"
}
```

### WRONG\_PROTOCOL

**Message:** "Unsupported protocol. Please switch to a supported chain or asset."

**Scenarios:**

* Protocol not in SUPPORTED\_PROTOCOLS list
* Protocol disabled in client configuration

### SELECTED\_PROTOCOL\_IS\_NOT\_SET

**Message:** "Selected protocol field is not set in deposit request."

**Scenarios:**

* `selected_protocol` missing from deposit request
* Empty string provided

### SELECTED\_QUOTE\_IS\_NOT\_SET

**Message:** "Selected quote field is not set in deposit request."

**Scenarios:**

* `quote_id` missing from deposit request
* Empty or invalid UUID format

### WRONG\_QUOTE\_FORMAT

**Message:** "Received malformed quote data. Please try again."

**Scenarios:**

* Quote missing required fields (from\_asset, to\_asset, amount)
* Invalid quote structure from protocol
* Corrupted database record

### IN\_ADDRESS\_IS\_WRONG\_FORMAT

**Message:** "Invalid input token address."

**Scenarios:**

* Malformed blockchain address
* Address checksum failure (EVM chains)
* Wrong address format for chain type

### OUT\_ADDRESS\_IS\_WRONG\_FORMAT

**Message:** "Invalid output token address."

**Scenarios:**

* Destination address invalid for target chain
* Address checksum failure
* Unsupported address format

### INVALID\_TOLERANCE\_BPS

**Message:** "Liquidity tolerance basis points must be less than 10,000 (100%). Please adjust your tolerance."

**Scenarios:**

* slippage\_bps >= 10000
* Negative slippage value

### CONFLICTING\_TOLERANCE\_PARAMS

**Message:** "Conflicting tolerance parameters. Use only one of tolerance\_bps or liquidity\_tolerance\_bps."

**Scenarios:**

* Both tolerance\_bps and liquidity\_tolerance\_bps provided (MAYA)
* Mutually exclusive parameters set

## Balance & Amount Errors (HTTP 400)

### INSUFFICIENT\_BALANCE

**Message:** "Insufficient balance (including gas fees)."

**Scenarios:**

* Wallet balance \< swap amount + gas fees
* Token balance insufficient for approval + swap

**Example Response:**

```json theme={null}
{
  "error": "Insufficient balance (including gas fees).",
  "status": 400,
  "code": "INSUFFICIENT_BALANCE",
  "context": {
    "required": "1.05 ETH",
    "available": "1.00 ETH"
  }
}
```

### NOT\_ENOUGH\_GAS

**Message:** "Account doesn't have sufficient balance to pay gas fees."

**Scenarios:**

* Native token balance insufficient for gas
* Gas estimate exceeds available balance

### UNDER\_DUST\_LIMIT

**Message:** "Output amount is too small (below dust limit) and would be lost. Increase input or choose another token."

**Scenarios:**

* Bitcoin output \< 546 satoshis
* Dogecoin output \< 1 DOGE
* Amount below minimum economically viable threshold

### BELOW\_MIN\_SWAP\_AMOUNT

**Message:** "Input amount is less than the minimum required for this swap (to cover fees). Increase your amount."

**Scenarios:**

* THORChain/MAYA amount \< recommended\_min\_amount\_in
* Swap amount insufficient to cover protocol fees

## Slippage & Price Errors (HTTP 400)

### OVER\_SLIPPAGE\_LIMIT

**Message:** "Slippage tolerance exceeded. Price moved more than allowed. Try increasing slippage or wait for stable prices."

**Scenarios:**

* Actual slippage > specified tolerance
* Price volatility during swap execution

### PRICE\_IMPACT\_TOO\_HIGH

**Message:** "Price impact is too high. The trade would move the market significantly."

**Scenarios:**

* Large swap in low-liquidity pool
* Price impact > 10%
* Relay/Rango flagged high impact

### OUTPUT\_BELOW\_PRICE\_LIMIT

**Message:** "Output amount is below your price limit due to slippage or fees. Adjust tolerance or try later."

**Scenarios:**

* THORChain emit\_asset \< price\_limit in memo
* Expected output degraded below minimum

### USE\_LOSES\_DANGEROUS\_AMOUNT

**Message:** "This trade is extremely unfavorable — you'd lose a large portion of your funds. Blocked for your protection."

**Scenarios:**

* Rango detected > 18% loss
* Swap would result in significant value loss
* Likely scam token or extreme price impact

## Quote Errors (HTTP 404)

### NO\_VALID\_QUOTE

**Message:** "No route found for this token pair. Try again later or use different tokens."

**Scenarios:**

* No protocols returned quotes
* All quotes failed validation
* Unsupported token pair

### ROUTE\_EXPIRED

**Message:** "This route has expired. Please request a new quote."

**Scenarios:**

* THORChain quote past expiry timestamp
* NEAR quote past timeWhenInactive
* Quote older than protocol timeout

### QUOTE\_ID\_DOESNT\_EXISTS

**Message:** "Quote id doesn't exist, try quoting again."

**Scenarios:**

* Invalid or fabricated quote\_id
* Quote not found in database
* Quote belongs to different client

### PROTOCOL\_DOESNT\_EXIST\_IN\_QUOTE

**Message:** "Given protocol doesn't exist for this quote. Use other protocols or request a new quote."

**Scenarios:**

* selected\_protocol not in quote's available protocols
* Protocol failed during quote generation

## Protocol-Specific Errors (HTTP 400)

### MEMO\_TOO\_LONG

**Message:** "Generated memo is too long for the source chain. Try using a shorter affiliate name or THORName."

**Scenarios:**

* Bitcoin memo > 150 bytes
* Dogecoin memo > 80 bytes
* OP\_RETURN data exceeds chain limit

### INVALID\_DEST\_ADDRESS

**Message:** "Destination address does not match the chain of the target asset. Please check the address and chain."

**Scenarios:**

* ETH address for BTC.BTC output
* Wrong address format for destination chain
* THORChain validation failed

### TOKEN\_NOT\_FOUND

**Message:** "Token not found or unsupported on this chain."

**Scenarios:**

* Asset not in tokens database
* Invalid asset identifier format
* Unsupported token contract address

### BLOCKCHAIN\_IS\_NOT\_SUPPORTED

**Message:** "This blockchain is not supported yet."

**Scenarios:**

* Chain not in supported ecosystems
* Ecosystem handler not implemented
* Chain disabled globally

### ALLOWANCE\_CANNOT\_BE\_SET

**Message:** "Failed to approve token spending. Check your wallet and try again."

**Scenarios:**

* ERC20 approval transaction construction failed
* Non-standard token contract
* Network congestion preventing gas estimation

## System Errors (HTTP 500)

### INTERNAL\_SERVER\_ERROR

**Message:** "Something went wrong on our side. Please try again later."

**Scenarios:**

* Uncaught exceptions
* Database connection failures
* External API timeouts

### DEPOSIT\_FAILED

**Message:** "Deposit transaction failed. Please try again."

**Scenarios:**

* Transaction construction error
* UTXO selection failed
* Gas estimation failed
* Protocol API error

### UNABLE\_TO\_RETRIEVE\_QUOTES

**Message:** "Can't retrieve quotes. Try again in a few seconds."

**Scenarios:**

* All protocol APIs down
* Network connectivity issues
* Rate limiting exceeded

### UNABLE\_TO\_RETRIEVE\_CHAINS

**Message:** "Failed to fetch chains price. Try again in a few seconds."

**Scenarios:**

* Price oracle unavailable
* Database read error
* CoinGecko API timeout

### UNABLE\_TO\_RETRIEVE\_USER\_BALANCE

**Message:** "Could not load wallet balance. Check connection and refresh."

**Scenarios:**

* Blockchain node unavailable
* RPC endpoint timeout
* Invalid address format

### UNABLE\_TO\_RETRIEVE\_TOKEN\_PRICE

**Message:** "Failed to fetch token price. Try again in a few seconds."

**Scenarios:**

* Price feed down
* Token not listed on price oracle
* Stale price data

### UNABLE\_TO\_RETRIEVE\_TRANSACTION\_FEE

**Message:** "Could not estimate gas fees — network may be congested."

**Scenarios:**

* Gas oracle unavailable
* Network congestion
* Transaction simulation failed

## Authentication Errors (HTTP 403)

### CLIENT\_CONFIG\_IS\_NOT\_SET

**Message:** "Unknown Api-Key"

**Scenarios:**

* Invalid API key
* API key not found in database
* Expired or revoked key

## Transaction Errors (HTTP 400)

### INVALID\_TRANSACTION\_HASH

**Message:** "Invalid transaction hash provided."

**Scenarios:**

* Malformed tx hash format
* Wrong length for chain type
* Non-hexadecimal characters

### TX\_ID\_IS\_NOT\_SET

**Message:** "Transaction ID is not set."

**Scenarios:**

* Missing tx\_id in status request
* tx\_id not saved and not provided

## Tracing Errors (HTTP 400/404)

### TRACE\_ID\_IS\_NOT\_SET

**Message:** "Trace ID is missing, please add ID that you want to track to end of the URL."

**Scenarios:**

* Empty traceId parameter
* Missing path parameter

### TRACE\_ID\_DOES\_NOT\_EXIST

**Message:** "This Trace ID does not exist."

**Scenarios:**

* Invalid trace ID
* Trace log expired (>30 days)
* Non-existent error log

## Other Errors

### ACCOUNT\_NOT\_FOUND

**Message:** "Account is not found. Please check your address."

**Scenarios:**

* Cosmos account not initialized
* Address never received funds
* Wrong chain for address format

### WRONG\_DEPOSIT\_FORMAT

**Message:** "Invalid deposit data for the selected route."

**Scenarios:**

* Corrupted deposit transaction
* Invalid PSBT format
* Missing required transaction fields

### PROTOCOL\_IS\_NOT\_SUPPORTED

**Message:** "Given protocol is not supported for this action."

**Scenarios:**

* Protocol doesn't support requested operation
* Ecosystem incompatibility
* Feature not implemented for protocol

## HTTP Status Code Summary

| Status Code | Category     | Description                            |
| ----------- | ------------ | -------------------------------------- |
| 200         | Success      | Request completed successfully         |
| 400         | Client Error | Validation, parameter, or quote errors |
| 403         | Forbidden    | Authentication failures                |
| 404         | Not Found    | Quote or resource not found            |
| 500         | Server Error | Internal errors, external API failures |

## Error Handling Best Practices

1. **Always check the `code` field** for programmatic error handling
2. **Display the `error` message** to users for user-friendly feedback
3. **Use `context` field** when available for additional error details
4. **Implement retry logic** for 500-level errors with exponential backoff
5. **Save trace\_id** from error responses for debugging support requests
6. **Validate inputs client-side** to reduce 400-level errors
7. **Handle partial failures** gracefully when fetching quotes from multiple protocols