Error Handling

Error response format, common error codes, and troubleshooting

Error Response Format

All errors return a consistent JSON structure:

{
  "statusCode": 400,
  "message": "Not enough balance. Current balance: 500000000000000000",
  "error": "Bad Request",
  "timestamp": "2025-01-15T12:00:00.000Z",
  "path": "/swap/v1/999/swap"
}

Field	Type	Description
statusCode	integer	HTTP status code
message	string	Human-readable error description
error	string	Error category
timestamp	string	ISO 8601 timestamp
path	string	Request path that produced the error

Common Errors

400 Bad Request

Message	Cause	Fix
src must be an Ethereum address	Invalid source token address	Use a valid 0x-prefixed 40-character hex address
dst must be an Ethereum address	Invalid destination token address	Same as above
amount should be positive integer string	Amount is missing, negative, or not a number	Pass a positive integer string in wei
No route found for the given token pair	No liquidity path exists between the two tokens	Verify both tokens exist on the chain and have liquidity
Not enough balance. Current balance: ...	Wallet balance is insufficient for the swap amount	Reduce the amount or fund the wallet
Not enough allowance. Current allowance: ...	AKKA Router is not approved to spend enough tokens	Call /approve/transaction first and submit the approval
slippage must not be greater than 50	Slippage exceeds the 50% maximum	Use a value between 0 and 50

404 Not Found

Message	Cause	Fix
Chain not found	Unsupported chain ID	Use a supported chain ID
Token not found	Token does not exist on the specified chain	Verify the token address on a block explorer
No spender contract found	No AKKA Router deployed on this chain	Use a chain with a deployed router

429 Too Many Requests

You exceeded the rate limit of 20 requests per 60 seconds. Wait for the rate limit window to reset.

500 Internal Server Error

An unexpected error occurred. If this persists, contact support on Telegram.

Troubleshooting

My swap transaction reverted on-chain

This usually means the price moved beyond your slippage tolerance between the quote and execution. Increase the slippage parameter (e.g., from 1 to 3) or execute the swap faster after getting the quote.

I get 'No route found' for a token I know exists

The token may exist on-chain but have no liquidity in any DEX pool that AKKA indexes. Check that the token has active trading pairs on at least one supported DEX.

Allowance check returns 0 even after approving

Make sure the approval transaction was confirmed on-chain before checking the allowance. If you approved a specific amount and already swapped some tokens, the remaining allowance may be less than expected.

Gas estimation seems too high

The API adds a 20% safety buffer to gas estimates. The actual gas used will typically be lower. You can override the gas limit using the gasLimit parameter on the swap endpoint.