On this page
Handle errors
Separate wallet rejection, RPC failure, source revert and destination failure.
- A disconnected wallet needs Connect, not a disabled transaction button.
- A rejected network switch should leave the form intact and show a useful toast.
- An unavailable asset read must not be interpreted as an asset that does not exist.
- A malformed nonempty compliance address must never fall back to creating an asset without an issuer compliance contract.
- A missing peer is not the same as a chain awaiting asset-owner approval.
- A delivered owner message can contain
OwnerActionRejectedorStaleConfigIgnored. - A failed destination transfer needs retry or restore, not another source send.
Decode protocol errors, refresh quotes after state changes, and preserve the source hash and GUID for recovery. Do not promise an exact delivery time.
Map failures to actions
| Failure | User action |
|---|---|
| UnknownAsset or missing facade code | Verify release, source chain and exact issuer identity |
| ChainNotEnabled | Issuer enables the destination, or syncs a stale remote source from the origin or enables it there directly |
| NoPeer | Route is not configured; enabling the asset alone cannot fix it |
| NotAssetOwner / NotOriginChain | Call from the permanent creator address; messages to other chains are sent from the origin |
| InvalidCompliance / NotCompliant | Inspect the configured policy and permissions; do not bypass it |
| NotEnoughNative | Re-quote and fund source native payment plus transaction gas |
| InsufficientReceiveGas | Re-execute the packet at the Endpoint with more gas. Nothing is lost or recorded as failed |
| Transfer pending far longer than usual on one route | The route may be down; stop offering it and route around it. See Route outages |
| SlippageExceeded | Refresh quote and review the new minimum; do not silently remove the guard |
| MessageMismatch / NotFailed | Recheck GUID, router state and exact packet before recovery |
| RestoreNotAllowedYet | Use the designated restorer or wait for the recorded grace period |
| HTTP 429 or 5xx | Back off for read requests; preserve transaction state |
These categories are not interchangeable. Decode revert data with the release ABI, and only show an insufficient-balance message when a balance check or decoded error supports it. Never log private keys, RPC credentials or entire nested provider errors.