> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.0x.org/llms.txt.
> For full documentation content, see https://docs.0x.org/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.0x.org/_mcp/server.
# Issues & Error Codes
> Learn about 0x API issues and error codes and how to resolve them.
# Handling API Issues and Error Codes
When working with the 0x API v2, there are two key places to check for errors:
1. [**The `issues` object**](/docs/introduction/api-issues#issues-object): This is returned in the API response when there are validation issues with a quote. It helps identify problems such as insufficient token allowance, low balances, or invalid liquidity sources that could prevent a successful swap execution.
2. [**Error codes**](/docs/introduction/api-issues#error-codes): These are returned when there is an issue making the API request itself, such as invalid input or authorization errors.
***
## Issues Object
By examining both the [`issues` object](/api-reference/openapi-json/swap/allowanceholder-getprice) for quote validation and the error codes for request failures, developers can troubleshoot and resolve issues more efficiently, ensuring smoother transaction processes.
In rare cases where 0x cannot fully validate a quote, the API returns `true` in `issues.simulationIncomplete`. Developers are encouraged to check and address these issues before proceeding with the swap.
```json
// Sample response from /swap/permit2/quote with an issues object
{
"issues": {
"allowance": {
"actual": "0",
"spender": "0x000000000022d473030f116ddee9f6b43ac78ba3"
},
"balance": {
"token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"actual": "0",
"expected": "100000000"
},
"simulationIncomplete": false,
"invalidSourcesPassed": []
}
}
```
### Issue Types and Resolutions
Below is a list of the common issues that may arise when using the `/price` or `/quote` endpoints, along with their causes and resolutions:
| **Issue** | **Reason** | **Details** |
| -------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **`allowance`** | The `taker` does not have sufficient token allowance to execute the swap. | The response provides the current and required allowance details. Prompt the user to set the correct token allowance. |
| **`balance`** | The `taker` does not have enough of the `sellToken` to complete the swap. | The response provides the actual and expected balances. Advise the user to ensure they have enough tokens to perform the swap. |
| **`simulationIncomplete`** | 0x cannot fully validate the transaction, often due to insufficient balance. | This doesn’t guarantee the swap will fail. Investigate if the user’s balance is low or if other conditions prevent validation. |
| **`invalidSourcesPassed`** | One or more invalid liquidity sources were included in the `excludedSources` list. | The response provides invalid sources. Remove invalid sources or check the valid list using `GET /sources`. |
This table format provides a concise and structured way to convey the relevant information about each issue, helping developers quickly understand the cause and resolution for each one.
### Best Practices for Handling Issues
#### Price Requests
* **`allowance`**: If returned, prompt the user to set the appropriate token allowance before proceeding.
* **`balance`**: Avoid proceeding to the quote stage if the user does not have enough tokens, as indicated by this field.
* **`simulationIncomplete`**: Safe to ignore for price requests. This issue may arise if the `taker` address is set but has an insufficient token balance.
#### Quote Requests
* **`allowance`**: Ensure that users complete the allowance setup before proceeding.
* **`balance`**: This field indicates insufficient token balance; prompt the user to check their balance and retry.
* **`simulationIncomplete`**: Advise users that validation could not be completed, but the trade may still succeed.
## Error Codes
In addition to the `issues` object, the API may return specific error codes under certain conditions. If the error persists, please [contact support](/docs/introduction/need-help#-contact-developer-support-fastest-direct-help) for assistance.
Common Error Codes
### Swap API
| **Code** | **Reasons** | **Details** |
| -------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | INPUT\_INVALID
SWAP\_VALIDATION\_FAILED
TOKEN\_NOT\_SUPPORTED | Ensure the API request is properly formatted.
Check that the `taker`, `sellToken`, and `buyToken` addresses are correct. For [native tokens](/docs/0x-swap-api/additional-topics/handling-native-tokens) (on any chains we support), you can use the contract address `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`. |
| 403 | TAKER\_NOT\_AUTHORIZED\_FOR\_TRADE | The `taker` address is not authorized to make this trade. Contact [0x API Support](https://docs.0x.org/docs/introduction/need-help#-contact-developer-support-fastest-direct-help) to investigate. |
| 422 | BUY\_TOKEN\_NOT\_AUTHORIZED\_FOR\_TRADE
SELL\_TOKEN\_NOT\_AUTHORIZED\_FOR\_TRADE | Ensure the `taker`, `sellToken`, and `buyToken` addresses are accurate. |
| 500 | INTERNAL\_SERVER\_ERROR
UNCATEGORIZED | An unexpected error has occurred.
Contact [0x API Support](https://docs.0x.org/docs/introduction/need-help#-contact-developer-support-fastest-direct-help) to investigate. |
### Gasless API
| Code | Reasons | Details |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | INPUT\_INVALID
SWAP\_VALIDATION\_FAILED
TOKEN\_NOT\_SUPPORTED
SELL\_AMOUNT\_TOO\_SMALL
INSUFFICIENT\_BALANCE
UNABLE\_TO\_CALCULATE\_GAS\_FEE | Ensure that the API request was formatted properly.
Check that the `taker`, `sellToken`, and `buyToken` addresses are correct. For [native tokens](/docs/0x-swap-api/additional-topics/handling-native-tokens) (on any chains we support), you can use the contract address `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`.
The provided `sellAmount` may be too small.
Check that the `taker` has enough `sellToken`. |
| 403 | TAKER\_NOT\_AUTHORIZED\_FOR\_TRADE | The `taker` address is not authorized to make this trade. Contact [0x API Support](https://docs.0x.org/docs/introduction/need-help#-contact-developer-support-fastest-direct-help) to investigate. |
| 404 | META\_TRANSACTION\_STATUS\_NOT\_FOUND | Check that the trade was submitted correctly. |
| 422 | BUY\_TOKEN\_NOT\_AUTHORIZED\_FOR\_TRADE
SELL\_TOKEN\_NOT\_AUTHORIZED\_FOR\_TRADE | Check that the `taker`, `sellToken`, and `buyToken` addresses are accurate. |
| 500 | INTERNAL\_SERVER\_ERROR
UNCATEGORIZED | An unexpected error has occurred.
[Contact support](https://docs.0x.org/docs/introduction/need-help#-contact-developer-support-fastest-direct-help) to resolve the issue. |