Error Handling & Troubleshooting

Common Error Codes

Error Message	Cause	Resolution
`BridgeSDK: apiKey is required`	SDK initialized without an API key.	Pass a valid `apiKey` to the `BridgeSDK` constructor.
`Insufficient funds`	Wallet balance too low for amount + gas fees.	Top up your wallet — ETH for EVM chains, TAO for Bittensor.
`Batch Interrupted`	A Bittensor batch transaction failed mid-execution.	Usually means the `transferStake` succeeded but the `remark` failed, or vice versa. Check the block explorer and retry.
`Slippage Exceeded`	Swap price moved significantly between quote and execution.	Retry the transaction. Consider using a higher slippage tolerance if supported.
`Invalid subnetId`	Bridge called without a required `subnetId`.	Use `subnetId: 0` for TAO; use the specific subnet ID (e.g. `1`) for Alpha tokens.

Symptom: sdk.wallets.bittensor.connect() throws an error or hangs indefinitely.

Fixes:

Ensure the user has a compatible browser extension installed (MetaMask for EVM, Talisman / Subwallet / Polkadot.js for Bittensor).
Check whether another DApp is actively using the extension and may be blocking the connection request.
Try reloading the page and connecting again.

Symptom: A failure event appears on the Bittensor block explorer after sending a batch transaction.

Fixes:

Verify the sending wallet has enough TAO to cover both the transfer amount and the transaction fee.
Confirm the toAddress (Bridge Hot Wallet) matches the correct address for your current environment (devnet, testnet, or mainnet).
If the failure persists, try submitting the two extrinsics separately to identify which one is failing.

Symptom: MetaMask shows “Transaction failed” or “Execution reverted”.

Fixes:

Verify that toToken is in the list of supported assets for the target chain.
Check that the bridge amount meets the minimum required threshold — the SDK will return an error for amounts that are too low, but on-chain reverts can also occur if conditions change between quote and execution.
For CCIP operations, ensure you have approved the router contract to spend your source tokens before sending the transaction. See CCIP Routing for details.

Symptom: SDK calls fail with Unauthorized, Forbidden, or a message about an expired or invalid session.

Fixes:

Verify your apiKey and (for server use) secretKey exactly match the values shown in the VoidAI Admin Portal.
The SDK authenticates via POST /api/v1/auth/login — if this login request fails, all subsequent API calls will be rejected.
Check that your tenant account has sufficient quota remaining in the Admin Portal.
For frontend integrations, confirm that your application’s domain is listed in the Domain Whitelist in the Tenant Portal. Requests from non-whitelisted origins are rejected.