Error Handling

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": "/partner/v1/999/quote"
}

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
Non-empty `issues` in a `200` response	Payer balance, gas, or allowance is insufficient	Resolve each issue and request a fresh quote
A validation status is `UNKNOWN`	An RPC validation lookup failed	Validate that check independently before broadcasting
`partner slippage must not exceed 5%`	Partner slippage exceeds the maximum	Use a value between 0 and 5

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 API-key or IP limit. Honor Retry-After when present and use bounded exponential backoff. Partner production limits are agreed during onboarding.

500 Internal Server Error

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

Troubleshooting

My swap transaction reverted on-chain

Discard the calldata and request a fresh partner quote. Ask the user before changing slippage; never automatically retry a reverted transaction or reuse signed RFQ calldata.

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 and targeted the quote’s allowanceTarget. Request a fresh partner quote after confirmation; the old executable response is stale.

Gas estimation seems too high

The API adds a safety buffer and may use a conservative route floor when RPC simulation cannot represent execution-time state. Inspect simulation.status; simulate independently when it is not SUCCESS. A wallet may raise the returned gas limit, but should not lower it.

Getting Started

Guides

Resources

Error Response Format

Common Errors

400 Bad Request

404 Not Found

429 Too Many Requests

500 Internal Server Error

Troubleshooting

​Error Response Format

​Common Errors

​400 Bad Request

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​Troubleshooting

Error Response Format

Common Errors

400 Bad Request

404 Not Found

429 Too Many Requests

500 Internal Server Error

Troubleshooting