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

# React Native


## SDK errors

### Platform Pay account change 

When you collect Platform Pay before registration or authentication, while the SDK has no crypto customer ID, the payment method belongs to the onramp merchant of record selected at collection time. The customer’s KYC region can require a different merchant of record after authentication or KYC submission. In that case, `createCryptoPaymentToken` can’t use the selected payment method and returns one of these `error.stripeErrorCode` values:

| Platform | `stripeErrorCode`                   |
| -------- | ----------------------------------- |
| iOS      | `payment_method_kyc_region_changed` |
| Android  | `platform_pay_account_changed`      |

Keep the authenticated SDK instance and ask the customer to collect Platform Pay again. Retry `createCryptoPaymentToken` only after collection succeeds. Token creation doesn’t reopen the wallet sheet automatically. An accurate `countryHint` reduces the likelihood of this error but doesn’t override the customer’s established KYC region.

On iOS with native [SDK 26.14.0](https://github.com/stripe/stripe-ios/releases#release-26.14.0), this recovery error only applies when no crypto customer ID existed at collection time. If you collect Apple Pay after registration or authentication and then submit KYC that changes the region, token creation can instead return `crypto_onramp_invalid_parameter` for `payment_method`. Establish the customer’s KYC region before collection in that sequence. See [iOS Platform Pay account changes](https://docs.stripe.com/crypto/onramp/embedded-components-error-handling-guide.md?platform=ios#platform-pay-account-change) for details.

Check `stripeErrorCode` for these errors. The general `error.code` is `Failed`:

```javascript
const result = await createCryptoPaymentToken();
if (result.error) {
  const code = result.error.stripeErrorCode;
  if (
    code === 'payment_method_kyc_region_changed' ||
    code === 'platform_pay_account_changed'
  ) {
    // Ask the customer to select Platform Pay again.
    // After collection succeeds, retry createCryptoPaymentToken.
  } else {
    // Handle other token creation errors.
  }
  return;
}
// Use result.cryptoPaymentToken to create the onramp session.
```

## 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=react-native#travel-rule-wallet-ownership) wallet ownership methods resolve with an `error` whose `stripeErrorCode` is one of the following:

| **stripeErrorCode**                                | **Description**                                                                                                 | **How to handle**                                                               |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `crypto_onramp_wallet_not_found`                   | The wallet isn’t registered on the authenticated user.                                                          | Register the wallet with `registerWalletAddress`, then request a new challenge. |
| `crypto_onramp_unsupported_network`                | The network doesn’t support wallet ownership verification. It only supports EVM-compatible networks and Solana. | Don’t retry with this network.                                                  |
| `crypto_onramp_wallet_ownership_challenge_expired` | The challenge expired.                                                                                          | Request a new challenge, collect a new signature, then submit again.            |
| `crypto_onramp_invalid_wallet_ownership_challenge` | The challenge is invalid or was already used.                                                                   | Request a new challenge, then submit again.                                     |
| `crypto_onramp_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. |