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

# Troubleshooting

> Common issues, error types, and debugging tips for the 0x Cross Chain API.

The 0x Cross-Chain API is in private beta. [Request access](https://0x.org/products/cross-chain) 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:

```json
{
  "name": "INPUT_INVALID",
  "message": "The input is invalid",
  "data": {
    "zid": "0xabc123...",
    "details": [
      { "field": "originTxHash", "reason": "Multiple cross-chain operations found in transaction; provide quoteId to disambiguate" }
    ]
  }
}
```

* `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 Name              | HTTP | Description                                                              |
| ----------------------- | ---- | ------------------------------------------------------------------------ |
| `INPUT_INVALID`         | 400  | Bad parameters, unsupported chain, ambiguous transaction, blocked wallet |
| `TRANSACTION_NOT_FOUND` | 404  | Origin tx not found on-chain                                             |
| `BRIDGE_UNKNOWN`        | 404  | Can't identify bridge for the given transaction                          |
| `BRIDGE_PROVIDER_ERROR` | 500  | Bridge provider API unavailable. Retry after a short delay               |
| `INTERNAL_SERVER_ERROR` | 500  | Unexpected server error                                                  |

## Common `INPUT_INVALID` Errors

| `data.details[].reason`                                                                   | Fix                                                                             |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `"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

| Issue                                               | Possible Cause                                                                                | Suggested Fix                                                                                                                                                |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Transaction fails or gets dropped                   | Insufficient SOL/ETH/etc. for gas fees, network congestion, insufficient balance or allowance | Ensure 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 errors                       | Wrong signer, unsigned transaction, or corrupted transaction data                             | Verify the transaction is signed by the correct keypair (or keypairs)                                                                                        |
| RPC timeout or errors during transaction submission | Network issues or overloaded RPC node                                                         | Try switching to a different RPC endpoint or add retries                                                                                                     |
| Unexpected API errors or bad responses              | Incorrect API key or malformed request payload                                                | Double-check API keys, endpoint URLs, and request parameters                                                                                                 |

## Debugging Tips

* Log your transaction hash and monitor it on corresponding transaction explorer (e.g. [Basescan](https://basescan.org/))
* 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.