Skip to main content

​
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: 
{
  "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: 
{
  "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 CodeCategoryDescription
200SuccessRequest completed successfully
400Client ErrorValidation, parameter, or quote errors
403ForbiddenAuthentication failures
404Not FoundQuote or resource not found
500Server ErrorInternal 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