Reference & Support
Troubleshooting
Common integration problems and what to do.
| Situation | Code or sign | What to do |
|---|---|---|
| Wallet not yet deployed on a network | chain_unavailable (409) | Wait for the wallet to be deployed, then retry. |
| Wrong wallet, or none found | wallet_not_found (404) | Send x-customer-id. |
| Passkey approval rejected | passkey_credential_invalid | Sign the exact hash or challenge returned, with a registered passkey. |
| Not enough for amount and fees | insufficient_funds | Quote first, and send at most the quoted maximum. |
| Transfer quote expired | validation_failed (409) | Quote and prepare again; submit before quoteExpiresAt. |
| Transfer stuck | bridge.stalled | Read Get bridge and contact us with the transfer id. |
| Network fee not sponsored | paymaster_rejected | Retry. |
| Timeouts | upstream_unavailable, 504 | Read the operation's state before retrying. See Reliability. |
| No notifications arriving | — | Check exact event names, a public https URL and the right project. |
| Live key refused | kyb_required | Complete business verification. |
| Retry refused: "retry shortly" | idempotency_conflict (409) | The first request is still running. Wait, then retry the same request. |
| Retry refused: "needs reconciliation" | idempotency_conflict (409) | An earlier attempt may have reached the network. Do not resend; read List transactions. |
| Passkey does not own the wallet | passkey_credential_invalid (409) | Use the passkey registered for this wallet; read List passkeys. |
| Wallet under recovery | forbidden (409) | Swaps and transfers are blocked until the recovery completes or is cancelled. |
| EVM signature refused over the challenge | expectedChallenge in the error | Send the base64url encoding of the userOpHash bytes, not the hash as text. |
| Deposit seen but not credited | deposit.detected only | Wait for deposit.confirmed before crediting the customer. |
| Too many requests | rate_limit_exceeded (429) | Back off and retry with increasing delays. |