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

# Error Handling

> Error response format, common error codes, and troubleshooting

## Error Response Format

All errors return a consistent JSON structure:

```json theme={null}
{
  "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](/supported-chains) |
| 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](https://t.me/akka_finance).

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>