# Error handling

Handle errors that occur during onramp sessions.

For general error handling, see the [Stripe error handling guide](https://docs.stripe.com/error-handling.md).

For error codes specific to the crypto onramp, see [Crypto onramp error codes](https://docs.stripe.com/crypto/onramp/embedded-components-error-codes.md).

# Web


## API errors

### Transaction blocked errors

Transactions can be blocked to meet compliance or risk requirements. For compliance reasons, Stripe can’t provide additional details about why a specific transaction was blocked. If you believe a transaction was blocked incorrectly, contact Stripe.

| Error code                          | Description                                                          | How to handle                                                                                         |
| ----------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `crypto_onramp_transaction_blocked` | The transaction was blocked to meet compliance or risk requirements. | Show a generic error message. If you believe the transaction was blocked incorrectly, contact Stripe. |

> When testing, use the [test values](https://docs.stripe.com/crypto/onramp/embedded-components-integration-guide.md?platform=android#test-values) to avoid triggering compliance or risk checks.

### Wallet ownership verification errors

The `getWalletOwnershipChallenge` and `submitWalletOwnershipSignature` [EU Travel Rule](https://docs.stripe.com/crypto/onramp/eu-kyc-integration-guide.md?platform=web#travel-rule-wallet-ownership) wallet ownership methods reject with an error whose `code` is one of the following:

| **code**                             | **Description**                                                                                                 | **How to handle**                                                               |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `WALLET_NOT_FOUND`                   | The wallet isn’t registered on the authenticated user.                                                          | Register the wallet with `registerWalletAddress`, then request a new challenge. |
| `UNSUPPORTED_NETWORK`                | The network doesn’t support wallet ownership verification. It only supports EVM-compatible networks and Solana. | Don’t retry with this network.                                                  |
| `WALLET_OWNERSHIP_CHALLENGE_EXPIRED` | The challenge expired.                                                                                          | Request a new challenge, collect a new signature, then submit again.            |
| `INVALID_WALLET_OWNERSHIP_CHALLENGE` | The challenge is invalid or was already used.                                                                   | Request a new challenge, then submit again.                                     |
| `INVALID_WALLET_OWNERSHIP_SIGNATURE` | The signature doesn’t prove control of the wallet.                                                              | Restart the full challenge and signing flow. Don’t resubmit the same signature. |

These codes are consistent across the web, React Native, Android, and iOS SDKs. Other failures—such as an unauthenticated user or a rate-limited request—aren’t specific to wallet ownership verification and reject with the non-specific `GENERIC_ONRAMP_ERROR` code. Handle them with your general error handling.