Skip to main content

​
Error response format

All errors follow the same envelope: 
{
  "success": false,
  "error": "descriptive error message"
}

​
Common errors

HTTP StatusErrorCauseFix
400invalid inputMintMint address is not valid base58Check the token mint address
400invalid amountAmount is not a valid number or is zeroUse string representation of the amount in smallest units
400invalid swapModeMust be ExactIn or ExactOutCheck the swapMode parameter
404no route foundNo liquidity path exists for this pair/amountTry a smaller amount, different slippage, or check if the token is supported
404no pool foundNo pool exists for one of the hopsThe token may not have any listed pools
400insufficient liquidityPools exist but don’t have enough liquidity for this amountReduce the swap amount
500simulation failedTransaction simulation failed on-chainCheck simulation logs, ensure wallet has sufficient balance
429(rate limit)Too many requestsBack off and retry with exponential delay

​
Handling errors in code

response=$(curl -s -w "\n%{http_code}" "https://api.argyros.xyz/api/v1/quote?inputMint=INVALID&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=1000000000&swapMode=ExactIn")
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)

if [ "$http_code" != "200" ]; then
  echo "Error ($http_code): $body"
fi

​
Simulation errors

When skipSimulation is false (default), the swap endpoint simulates the transaction before returning it. Check the simulation field in the response: 
{
  "simulation": {
    "success": false,
    "error": "insufficient funds",
    "insufficientFunds": true,
    "slippageExceeded": false,
    "computeUnitsConsumed": 0,
    "logs": ["Program log: Error: insufficient lamports"]
  }
}
FieldMeaning
insufficientFundsWallet doesn’t have enough tokens for the swap + transaction fees
slippageExceededPrice moved beyond the slippage tolerance between quote and transaction build

​
On-chain transaction errors

Even after a successful simulation, the transaction can fail on-chain if conditions change between simulation and confirmation.
ErrorCauseFix
SlippageExceededPrice moved after submissionIncrease slippageBps or retry quickly
InsufficientFundsBalance changed between simulation and executionRe-check balance before submitting
BlockhashExpiredTransaction took too long to confirmRebuild the transaction and resubmit

​
Retry strategy

Error categoryAction
Quote failures (404)Retry after 1-2 seconds. Liquidity can appear as pools rebalance.
Rate limits (429)Exponential backoff: 1s, 2s, 4s, 8s. Max 3 retries.
Simulation failures (500)Re-fetch a fresh quote and rebuild. Don’t retry the same transaction.
On-chain failuresGet a new quote (prices have likely changed) and rebuild from scratch.