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: 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: 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 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.

// 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 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 (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 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 to investigate.

Gasless API

Code	Reasons	Details
400	INPUT_INVALID SWAP_VALIDATION_FAILED TOKEN_NOT_SUPPORTED SELL_AMOUNT_TOO_SMALL INSUFFICIENT_BALANCE	Check that the API request was formatted properly. Check that the taker, sellToken, and buyToken addresses are correct. For native tokens (on any chains we support), you can use the contract address 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee. The provided sellAmount is 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 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 to resolve the issue.