> For the complete documentation index, see [llms.txt](https://docs.native.org/native-dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.native.org/native-dev/build-with-native/swap-aggregators/firmquote-swap-apis/miscellaneous/error-handling.md).

# Error Handling

## Error Handling

Requests with application or business logic errors will return with an HTTP code of 200, but with additional fields for error code and message. For example:

```json
{
  "code": 171008,
  "message": "not found token info"
}

{
  "code": 171018,
  "message": "expire time exceeds global limit 60s"
}
```

To verify the response status, check whether `code` is present in the response. Successful quote responses also carry `success: true`, but not every endpoint returns a `success` field.

Codes that are not individually mapped are normalised by the gateway: any code starting with `3` or `4` is returned as `quote invalid, risk management checks failed`, and any other unmapped code is returned as `failed to provide quote, mm not available` together with the original code.

{% hint style="info" %}
Please note that for endpoints that typically return an array, gateway-level errors (for example an invalid `chain`) are returned in object format, for example /orderbook. If the orderbook backend times out (1s), `/orderbook` returns an empty array `[]` with HTTP 200.
{% endhint %}

## Error Codes

The list of most common error codes returned by Swap APIs. For other unknown errors, please reach out to Native team members via an existing channel.

<table data-header-hidden><thead><tr><th width="96.18927001953125">Code</th><th width="229.49609375">Message</th><th>Reason</th><th>Mitigation</th></tr></thead><tbody><tr><td>301016<br>405030<br>(any 3xxxxx / 4xxxxx code)</td><td>quote invalid, risk management checks failed</td><td>The quote provided by the underlying private market maker is rejected by Native's risk managment system to protect swapper/taker.</td><td>This is usually caused by sudden, violent market movements and should never be persistent.<br><br>Simply try again after a few seconds of cooldown.</td></tr><tr><td>101010</td><td>quoted amount exceeds maximum available, please check /orderbook endpoint for levels</td><td>The quoting amount exceeds the maximum available liquidity/depth represented by levels in the <code>/orderbook</code> endpoint.</td><td>Please always refer to the up-to-date <code>/orderbook</code> results while quoting. And quote within the available depth.</td></tr><tr><td>171037</td><td>orderbook empty for quoted trade, please check /orderbook endpoint</td><td>The quoting trade currently has 0 available liquidity/depth, and is removed from the <code>/orderbook</code> endpoint.<br>Please always refer to the latest <code>/orderbook</code> results for quoting.</td><td>Please always refer to the up-to-date <code>/orderbook</code> results while quoting. And only quote existing orderbooks.</td></tr><tr><td>171011</td><td>requested pair not found</td><td>The requested pair is not supported by Native and can’t be found.</td><td>Refer to <code>/orderbook</code> results while quoting. And only quote existing orderbooks.<br><br>Or contact Native to enable AMM fallback.</td></tr><tr><td>171015</td><td>quoted token not available</td><td>The requested quote/buying token is not available.</td><td>Refer to <code>/orderbook</code> results while quoting. And only quote existing orderbooks.<br><br>Or contact Native to enable AMM fallback.</td></tr><tr><td>101007</td><td>quoted pair not available,empty orderbook</td><td>The quoting trade currently has 0 available liquidity/depth, and is removed from the <code>/orderbook</code> endpoint.<br>Please always refer to the latest <code>/orderbook</code> results for quoting.</td><td>Please always refer to the up-to-date <code>/orderbook</code> results while quoting. And only quote existing orderbooks.</td></tr><tr><td>131003</td><td>failed to parse parameters</td><td>Issues with input parameters. Usually due to incorrect formats.</td><td>Check input format. Avoid passing floats or non-integer values in integer params. A non-integer <code>amount_wei</code> returns <code>171009</code> (<code>token amount is wrong</code>) instead.</td></tr><tr><td>131004</td><td>invalid parameter</td><td>Issues with input parameters. Usually due to input conflicts.</td><td>Try avoid using duplicated params together like <code>amount</code> and <code>amount_wei</code></td></tr><tr><td>131011</td><td>front key version required</td><td><code>version</code> is required when calling Native’s public UI apiKey, and must not be empty or <code>1</code>.</td><td>Use <code>version=3</code> or above while quoting (we recommend always passing <code>version=6</code>; omitting it falls back to version 4, which will be deprecated soon).</td></tr><tr><td>171018</td><td>expire time exceeds global limit 60s</td><td>The requested <code>expiry_time</code> should not exceed 60s.</td><td>Remove or pass <code>expiry_time</code> of 60 or lower.</td></tr><tr><td>171053</td><td>fee bps exceeds limit 300</td><td>The commission fee should not exceed 300 bps.</td><td>Adjust <code>fee</code> to be 300 or lower.</td></tr><tr><td>131005</td><td>chain parameters invalid</td><td>Missing or unrecognised chain input (<code>src_chain</code> / <code>dst_chain</code> on quote endpoints, <code>chain</code> / <code>chainId</code> on <code>/orderbook</code>).</td><td>Refer to <a data-mention href="/native-dev/resources/networks.md">Networks</a>for supported networks. And use small-caps, standardised chain names.</td></tr><tr><td>131002</td><td>Internal Server Error</td><td>Unexpected gateway error.</td><td>Retry. If persistent, contact Native.</td></tr><tr><td>131006</td><td>request timeout</td><td>The quote backend did not respond in time (fixed 3s for quotes).</td><td>Retry after a short delay.</td></tr><tr><td>131010</td><td>invalid api id</td><td>The API key is not recognised for this endpoint.</td><td>Use the correct API key.</td></tr><tr><td>131012</td><td>exact out not support</td><td><code>exact_type=ExactOut</code> is only enabled for selected API keys.</td><td>Use ExactIn, or contact Native.</td></tr><tr><td>171009</td><td>token amount is wrong</td><td>Invalid or non-integer <code>amount_wei</code>.</td><td>Pass an integer string in wei, or use <code>amount</code>.</td></tr><tr><td>171055</td><td>seller token amount too small, min: %d (wei)</td><td>Amount is below <code>minimum_in_base</code> for the pair.</td><td>Quote at least the minimum from <code>/orderbook</code>.</td></tr><tr><td>171058 / 171073</td><td>multiple hop not support multiple pmm / exact out not support multiple hop</td><td>Multihop restrictions.</td><td>See Multihop.</td></tr><tr><td>171079</td><td>solana does not support native SOL as token_out</td><td>Native SOL cannot be the output token on Solana.</td><td>Use wrapped SOL as <code>token_out</code>.</td></tr><tr><td>201003</td><td>X-Forwarded-For is empty</td><td>Requests must carry a non-empty <code>X-Forwarded-For</code> header.</td><td>Add the header.</td></tr><tr><td>201009</td><td>no auth to call</td><td>The endpoint (for example <code>/blacklist</code> or <code>/is-black-address</code>) is not enabled for your key.</td><td>Contact Native to request permission.</td></tr><tr><td>201001</td><td>auth get api key is invalid</td><td>Auth error.</td><td>Use correct api key.</td></tr><tr><td>201005</td><td>rate reach limit</td><td>Per-API-key rate limit is hit (counted per 1-second window).</td><td>Reduce traffic.</td></tr></tbody></table>