Cross-Chain APIReference

Troubleshooting

View as Markdown

The 0x Cross-Chain API is in private beta. Request access to start building.

When working with 0x Cross Chain API, you may encounter some common issues. Below are tips to help diagnose and resolve them.

Error Response Format

All API error responses follow this structure:

1{
2  "name": "INPUT_INVALID",
3  "message": "The input is invalid",
4  "data": {
5    "zid": "0xabc123...",
6    "details": [
7      { "field": "originTxHash", "reason": "Multiple cross-chain operations found in transaction; provide quoteId to disambiguate" }
8    ]
9  }
10}
  • name - the error type (see table below)
  • message - human-readable description
  • data.zid - unique request identifier. Always include this when contacting support.
  • data.details - field-level errors (present for INPUT_INVALID)

Error Types

Error NameHTTPDescription
INPUT_INVALID400Bad parameters, unsupported chain, ambiguous transaction, blocked wallet
TRANSACTION_NOT_FOUND404Origin tx not found on-chain
BRIDGE_UNKNOWN404Can’t identify bridge for the given transaction
BRIDGE_PROVIDER_ERROR500Bridge provider API unavailable. Retry after a short delay
INTERNAL_SERVER_ERROR500Unexpected server error

Common INPUT_INVALID Errors

data.details[].reasonFix
"Multiple cross-chain operations found in transaction; provide quoteId to disambiguate"Pass quoteId from original quote. Happens with ERC-4337 bundlers.
"originChain and destinationChain must be different"Use different chains, this API does not support same-chain swaps.
"HyperCore is not supported as an origin chain"HyperCore (999999999992) is destination-only.
"Fee parameters are not supported..."Remove feeBps / feeRecipient. Fees only work on EVM origins.
"includedBridges and excludedBridges are mutually exclusive"Use only one of those parameters.
"feeBps and feeRecipient must have the same length"Match comma-separated array lengths.
"Address is not authorized for trading"Wallet is on a screening blocklist. data.details[].field shows which address.
"Quote ID not found in transaction metadata"The quoteId doesn’t match any cross-chain operation in the transaction.

Common Issues

IssuePossible CauseSuggested Fix
Transaction fails or gets droppedInsufficient SOL/ETH/etc. for gas fees, network congestion, insufficient balance or allowanceEnsure your wallet has enough SOL/ETH for fees, ensure you have enough balance for the trade, ensure you set proper allowance (see issues in API response)
Signature verification errorsWrong signer, unsigned transaction, or corrupted transaction dataVerify the transaction is signed by the correct keypair (or keypairs)
RPC timeout or errors during transaction submissionNetwork issues or overloaded RPC nodeTry switching to a different RPC endpoint or add retries
Unexpected API errors or bad responsesIncorrect API key or malformed request payloadDouble-check API keys, endpoint URLs, and request parameters

Debugging Tips

  • Log your transaction hash and monitor it on corresponding transaction explorer (e.g. Basescan)
  • Check API response error messages carefully; they often indicate what went wrong.
  • Make sure to monitor the status of your transaction via /status endpoint. Sometimes it might take more time to complete or refund a cross chain transfer. Make sure to pass quoteId when calling /status endpoint.
  • Check issues in quote responses as allowance, balance, and invalid name problems are reported here, not as errors.
  • Call /sources to verify the chain pair and bridge are supported.

If you continue to experience issues, consider reaching out to the 0x developer support for assistance.