Introduction

Issues & Error Codes

View as Markdown

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.

1// Sample response from /swap/permit2/quote with an issues object
2{
3  "issues": {
4    "allowance": {
5      "actual": "0",
6      "spender": "0x000000000022d473030f116ddee9f6b43ac78ba3"
7    },
8    "balance": {
9      "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
10      "actual": "0",
11      "expected": "100000000"
12    },
13    "simulationIncomplete": false,
14    "invalidSourcesPassed": []
15  }
16}

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:

IssueReasonDetails
allowanceThe 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.
balanceThe 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.
simulationIncomplete0x 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.
invalidSourcesPassedOne 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

CodeReasonsDetails
400INPUT_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.
403TAKER_NOT_AUTHORIZED_FOR_TRADEThe taker address is not authorized to make this trade. Contact 0x API Support to investigate.
422BUY_TOKEN_NOT_AUTHORIZED_FOR_TRADE
SELL_TOKEN_NOT_AUTHORIZED_FOR_TRADE		Ensure the taker, sellToken, and buyToken addresses are accurate.
500INTERNAL_SERVER_ERROR
UNCATEGORIZED		An unexpected error has occurred.
Contact 0x API Support to investigate.

Gasless API

CodeReasonsDetails
400INPUT_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 (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.
403TAKER_NOT_AUTHORIZED_FOR_TRADEThe taker address is not authorized to make this trade. Contact 0x API Support to investigate.
404META_TRANSACTION_STATUS_NOT_FOUNDCheck that the trade was submitted correctly.
422BUY_TOKEN_NOT_AUTHORIZED_FOR_TRADE
SELL_TOKEN_NOT_AUTHORIZED_FOR_TRADE		Check that the taker, sellToken, and buyToken addresses are accurate.
500INTERNAL_SERVER_ERROR
UNCATEGORIZED		An unexpected error has occurred.
Contact support to resolve the issue.