# Crypto onramp error codes

Learn about crypto onramp error codes.

Some [crypto onramp API](https://docs.stripe.com/api/crypto/.md) errors include a `code` attribute to help you handle errors programmatically in your integration. Find the error codes and messages below. An error is actionable if you or your customer can correct the underlying issue.



| Code | Description | Error messages | Actionable | Recommended handling |
| --- | --- | --- | --- | --- |
| `crypto_onramp_amount_above_maximum` | The purchase amount exceeds the maximum allowed amount. | {currency_symbol}{amount_limit} | Yes | Reduce the purchase amount to the maximum shown in the error message, then try again. |
| `crypto_onramp_amount_below_minimum` | The purchase amount is below the minimum allowed amount. | {currency_symbol}{amount_limit} | Yes | Increase the purchase amount to the minimum shown in the error message, then try again. |
| `crypto_onramp_bank_institution_block` | The selected bank institution is not eligible for crypto onramp ACH transactions. Try a different bank or payment method. | This bank isn’t supported for crypto purchases. Try again with a different bank account or debit card. | Yes | Ask the customer to select a different bank account or payment method. |
| `crypto_onramp_conflicting_destination_currency` | `transaction_details.destination_currency` isn’t in the `supported_destination_currencies` list. | `transaction_details.supported_destination_currencies` doesn’t contain `transaction_details.destination_currency`. Only use a supported destination currency for the suggested destination currency. | Yes | Use a destination currency from `supported_destination_currencies`, or update the supported currencies list. |
| `crypto_onramp_conflicting_destination_network` | `transaction_details.destination_network` isn’t in the `supported_destination_networks` list. | `transaction_details.supported_destination_networks` doesn’t contain `transaction_details.destination_network`. Only use a supported destination network for the suggested destination network. | Yes | Use a destination network from `supported_destination_networks`, or update the supported networks list. |
| `crypto_onramp_conflicting_source_total_amount_parameters` | The `source_total_amount`, `source_amount`, and `destination_amount` parameters are mutually exclusive. Provide one of these parameters. | The `source_total_amount`, `source_amount`, and `destination_amount` parameters are mutually exclusive. Only set one of these when creating an onramp session. | Yes | Provide only one of `source_total_amount`, `source_amount`, or `destination_amount`. |
| `crypto_onramp_consumer_wallet_doesnt_exist` | The wallet address doesn’t exist for the current user. | The wallet address doesn’t exist for the current user. | Yes | Use a wallet address that belongs to the current customer. |
| `crypto_onramp_currency_not_available_in_region` | The selected currency isn’t available in the customer’s KYC region. | Source currency {source_currency} isn’t supported in the user’s KYC region ({kyc_region}). Use a different source currency. | Yes | Ask the customer to select a source currency that’s available in their region. |
| `crypto_onramp_declaration_not_found` | No Common Reporting Standard (CRS) or Crypto-Asset Reporting Framework (CARF) declaration is available. | No CRS or CARF declaration is available. | No | Don’t retry the request. Contact Stripe support if you expect a declaration to be available. |
| `crypto_onramp_destination_tags_not_supported` | One or more networks in `destination_tags` don’t support destination tags. | The networks provided in `destination_tags` aren’t valid tag-based networks. | Yes | Remove destination tags for networks that don’t support them, or select a tag-based network. |
| `crypto_onramp_disabled` | We temporarily disabled the crypto onramp endpoint. | We temporarily disabled the `/v1/crypto/onramp_sessions` endpoint. We’ll contact you with outage details. | No | Pause requests and wait for Stripe to confirm that the service is available again. |
| `crypto_onramp_headless_invalid_amount` | The amount isn’t valid for headless mode. | The amount isn’t valid for headless mode. Provide a positive amount with no more than 2 decimal places. | Yes | Provide a positive amount with no more than two decimal places. |
| `crypto_onramp_headless_unsupported_currency_or_network` | Headless mode doesn’t support the provided currency or network. | Headless mode doesn’t support the provided currency or network. | Yes | Select a currency and network supported in headless mode. |
| `crypto_onramp_identity_verification_failed` | We couldn’t verify the customer’s identity. | We couldn’t verify your identity. Contact support for assistance. | No | Don’t retry identity verification. Ask the customer to contact Stripe support. |
| `crypto_onramp_incomplete_destination_currency_and_network_pair` | Provide both `transaction_details.destination_currency` and `transaction_details.destination_network`. | You must specify both `transaction_details.destination_currency` and `transaction_details.destination_network` if you specify either one. | Yes | Provide both `destination_currency` and `destination_network`, or omit both parameters. |
| `crypto_onramp_invalid_amount` | The purchase amount is invalid. | The {direction} purchase amount is {currency_symbol}{amount_limit} | Yes | Update the purchase amount according to the limit in the error message, then try again. |
| `crypto_onramp_invalid_currency_pair` | The source and destination currency pair isn’t supported. | This currency pair is invalid. | Yes | Ask the customer to select a supported source and destination currency pair. |
| `crypto_onramp_invalid_destination_currency_and_network_pair` | The `transaction_details.destination_currency` and `transaction_details.destination_network` pair isn’t supported. | The `transaction_details.destination_currency` and `transaction_details.destination_network` pair isn’t supported. | Yes | Provide a supported destination currency and network pair. |
| `crypto_onramp_invalid_destination_exchange_amount` | `transaction_details.destination_exchange_amount` must be a positive number. | The `destination_exchange_amount` value must be positive. Provide a positive amount. | Yes | Provide a positive `destination_exchange_amount`. |
| `crypto_onramp_invalid_merchant_configuration` | The merchant account is not properly configured for crypto onramp. Check the returned error message for more context, or contact your Stripe account executive or solutions architect for assistance. | - Allowlisted domains must be formatted as a valid domain name. Only use lowercase letters, numbers, dots, and hyphens.
- Business name not found. Fill in public business name in Settings.
- Terms of Service hasn’t been accepted. Accept terms of service before submitting application.
- High risk countries and regions attestation hasn’t been accepted. Accept the attestation before submitting application.
- We couldn’t secure your device for the current domain. Make sure that you’re on the correct domain to mitigate phishing attacks. | Yes | Follow the error message to correct your account or domain configuration. Contact your Stripe representative if you need help. |
| `crypto_onramp_invalid_parameter` | One or more of the provided parameters is invalid, missing, or conflicts with other parameters. Check our [API reference](https://docs.stripe.com/api/crypto.md) or the returned error message to see which values were not correct. | - {currency} is an invalid currency value for {param}. Select a supported currency.
- {network} is an invalid network value for {param}. Select a supported network.
- `transaction_details.wallet_address` is set, but `transaction_details.destination_networks` isn’t set. Set destination networks if you’re setting a wallet address.
- Use the proper quotes route for your onramp version. Use `/v1/crypto/onramp/quotes` for an integration with no beta header, or beta v1. Use `/v1/crypto/onramp_quotes` for beta v2.
- The wallet address specified is not compatible with the selected network.
- The parameter {param} provided to onramp advance is not valid for an onramp in state {state}.
- Request made on a user who doesn’t have an EU-based address.
- Invalid country code: {country_code}.
- Non-EU country code: {country_code}.
- The wallet address cannot be changed when locked. | Depends on the error message | Follow the error message to correct the request when possible. Don’t retry an unchanged request. |
| `crypto_onramp_invalid_payment_method` | The payment method could not be used for this crypto onramp transaction. Try a different payment method or check the returned error message for more context. | - The bank account must be linked before it can be used for this crypto purchase.
- We’re unable to confirm you are the owner of this bank account. Try again with a different payment method.
- This bank account isn’t eligible for this transaction. Please use a different bank account or payment method.
- This bank account doesn’t have enough transaction history for this crypto purchase. Try again with a different payment method.
- We’re unable to verify you own this card. Try again with a different card.
- Your card doesn’t support crypto purchases. Try again with a different card or pay using a bank account.
- This bank account doesn’t have enough funds for this crypto purchase. Try again with a different payment method or after adding funds.
- You’ve exceeded the number of payment methods on your Link account. Remove a few to transact.
- This payment method isn’t saved to your Link account. Add it before transacting. | Yes | Follow the error message to update the payment method, or ask the customer to select a different one. |
| `crypto_onramp_invalid_source_currency` | The provided source currency isn’t supported. | The source currency isn’t supported. | Yes | Provide a supported source currency. |
| `crypto_onramp_invalid_source_destination_pair` | The `source_exchange_amount` and `destination_exchange_amount` parameters are mutually exclusive. Provide one of these parameters. | `transaction_details.source_exchange_amount` and `transaction_details.destination_exchange_amount` are mutually exclusive. Only set one of these when creating an onramp session. | Yes | Provide only one of `source_exchange_amount` or `destination_exchange_amount`. |
| `crypto_onramp_invalid_source_exchange_amount` | `source_exchange_amount` must be a positive fiat amount with no more than two decimal places. | The `source_exchange_amount` value isn’t valid. Provide a positive fiat amount with no more than 2 decimal places. | Yes | Provide a positive fiat `source_exchange_amount` with no more than two decimal places. |
| `crypto_onramp_invalid_supported_destination_currencies_and_networks` | None of the provided destination currency and network pairs are supported. | None of the `transaction_details.destination_currency` and `transaction_details.destination_network` pairs are supported. | Yes | Provide at least one supported destination currency and network pair. |
| `crypto_onramp_invalid_wallet_address_parameters` | The `transaction_details.wallet_address` and `transaction_details.wallet_addresses` parameters are mutually exclusive. Provide one of these parameters. | `transaction_details.wallet_address` and `transaction_details.wallet_addresses` can’t both be set. | Yes | Provide only one of `wallet_address` or `wallet_addresses`. |
| `crypto_onramp_limit_exceeded` | The request could not be completed because a limit has been exceeded. | - Your purchase limit has been reached. Try a smaller amount.
- You’ve reached your purchase limit. Try again in a few hours. | Yes | Ask the customer to try a smaller amount or wait for the limit to reset, as directed by the error message. |
| `crypto_onramp_merchant_not_properly_setup` | Your Stripe account is missing the required `business_name` or `business_url` field. | Add `business_name` and `business_url` to your Stripe account before creating an onramp session. | Yes | Add `business_name` and `business_url` to your Stripe account, then try again. |
| `crypto_onramp_missing_destination_currency` | Provide `transaction_details.destination_currency` when you set `transaction_details.destination_exchange_amount`. | `transaction_details.destination_exchange_amount` is set, but `transaction_details.destination_currency` isn’t. Set a destination currency if you’re setting a destination exchange amount. | Yes | Provide `destination_currency` when you provide `destination_exchange_amount`. |
| `crypto_onramp_missing_document_verification` | The customer must complete document verification to continue. | Document verification is required to {action}. | Yes | Ask the customer to complete document verification, then try again. |
| `crypto_onramp_missing_identity_verification` | The customer must complete identity verification to continue. | Identity verification is required to {action}. | Yes | Ask the customer to complete identity verification, then try again. |
| `crypto_onramp_missing_minimum_identity_verification` | The customer hasn’t completed the minimum required identity verification. | Minimum identity verification is required for this transaction. | Yes | Ask the customer to complete the minimum required identity verification, then try again. |
| `crypto_onramp_missing_source_currency` | Provide `transaction_details.source_currency` when you set `transaction_details.source_exchange_amount`. | `transaction_details.source_exchange_amount` is set, but `transaction_details.source_currency` isn’t. Set a source currency if you’re setting a source exchange amount. | Yes | Provide `source_currency` when you provide `source_exchange_amount`. |
| `crypto_onramp_missing_source_total_amount_parameters` | When you set `source_total_amount`, provide `source_currency`, `destination_currency`, `destination_network`, and `preferred_payment_method`. | `source_total_amount` is set, but some of the `source_currency`, `destination_currency`, `destination_network`, or `preferred_payment_method` parameters aren’t set. Set all of these parameters if you’re setting a source total amount. | Yes | When you provide `source_total_amount`, also provide all parameters listed in the error message. |
| `crypto_onramp_missing_tax_attestation` | Submit a tax attestation before confirming the CRS or CARF declaration. | Submit a tax attestation before confirming the CRS or CARF declaration. | Yes | Submit the customer’s tax attestation before confirming the declaration. |
| `crypto_onramp_no_wallet_address_to_lock` | Provide a wallet address when you set `transaction_details.lock_wallet_address` to `true`. | `transaction_details.lock_wallet_address` is set to `true`, but no wallet address was provided in `transaction_details.wallet_address`. | Yes | Provide `wallet_address` before setting `lock_wallet_address` to true. |
| `crypto_onramp_quote_expired` | The crypto onramp quote is no longer valid. Fetch a new quote and retry the operation. | The exchange rate has moved significantly since your quote was locked. Fetch a new quote. | Yes | Fetch a new quote and retry the operation. |
| `crypto_onramp_quote_invalid_destination_currencies_and_networks` | None of the provided destination currency and network pairs are valid for the quote. | None of the `destination_currencies` and `destination_networks` pairs are supported. | Yes | Request the quote with at least one supported destination currency and network pair. |
| `crypto_onramp_quote_too_many_destination_currencies_and_networks` | When you set `destination_exchange_amount`, provide one `destination_currencies` entry and one `destination_networks` entry. | When you set `destination_exchange_amount`, provide one `destination_currencies` entry and one `destination_networks` entry. | Yes | When you provide `destination_exchange_amount`, provide exactly one destination currency and one destination network. |
| `crypto_onramp_service_error` | An error occurred while processing your crypto onramp request. Try again or contact support if the issue persists. | - We’re unable to continue with your purchase.
- An unrecoverable server error was encountered.
- The service timed out processing your request. Try again.
- An error occurred with your crypto purchase session. Try creating a new session or contact support if the issue persists.
- We couldn’t find the consumer account for this onramp session.
- We couldn’t find the consumer settings for this business. | No | Retry with exponential backoff. If the error continues, create a new session or contact Stripe support. |
| `crypto_onramp_session_error` | An error occurred while processing the crypto purchase session. Check the returned error message for more context. | - An error occurred with your crypto purchase session. Try creating a new session or contact support if the issue persists.
- The FX quote for this session is no longer valid. Refresh your quote and try again.
- Verify ownership of the destination wallet to complete this purchase, then try again. | Depends on the error message | Follow the error message: create a new session, refresh the quote, or ask the customer to verify wallet ownership. |
| `crypto_onramp_skip_quote_screen_not_allowed` | To set `skip_quote_screen` to `true`, provide `source_currency`, `destination_currency`, `destination_network`, and either `source_amount` or `destination_amount`. | To set `skip_quote_screen` to `true`, provide `source_currency`, `destination_currency`, `destination_network`, and either `source_amount` or `destination_amount`. | Yes | Provide all required currency, network, and amount parameters before setting `skip_quote_screen` to true. |
| `crypto_onramp_transaction_blocked` | The transaction was blocked and could not be processed. | - We’re unable to complete this request because the consumer account is closed.
- We’re unable to complete this request because the customer’s account is disabled.
- This transaction has been blocked. | No | Don’t retry the transaction. Tell the customer that the purchase can’t be completed. |
| `crypto_onramp_unsupportable_customer` | Crypto onramp doesn’t support the customer based on the information they provided. | Crypto onramp can’t support this customer based on the information they provided. | No | Don’t retry the transaction. |
| `crypto_onramp_unsupported` | The requested operation is not supported. Check the returned error message for more context. | - This crypto purchase cannot be completed because cross-border transactions are not supported.
- The issuing country of the identity document isn’t supported.
- We’re unable to support transactions in {state}.
- This service isn’t available in your current region.
- This payment method isn’t supported.
- Cannot purchase {currency} as a {location} resident.
- We’re unable to support transactions in {country}.
- The provided nationality is not supported.
- {id_type} is not a supported ID type. | Depends on the error message | Follow the error message. Ask the customer to select a supported payment method, identity document, or currency. Don’t retry if Stripe doesn’t support the customer’s country or region. |
| `crypto_onramp_unsupported_country` | Crypto onramp transactions aren’t available in the customer’s country. | Crypto onramp transactions aren’t available in this country. | No | Don’t retry the transaction. Tell the customer that crypto onramp isn’t available in their country. |
| `crypto_onramp_unsupported_region` | The provided region isn’t supported. | The provided region isn’t supported. Provide a supported ISO 3166-2 country-subdivision code. | Yes | Provide a supported ISO 3166-2 country-subdivision code. |
| `crypto_onramp_verification_error` | The request could not be completed due to a verification issue. Check the returned error message for more context. | - We need additional identity verification for you to purchase this amount.
- Consumer account {consumer_account} has incomplete KYC data.
- Basic KYC information must be submitted before this endpoint can be used.
- Consumer person verification is still processing. Try again shortly.
- Address couldn’t be verified.
- WebAuthn verification failed. Try again later or use a different method.
- We couldn’t verify your address. Update your address and try again.
- Identity verification is required to {action}.
- Document verification is required to {action}.
- We couldn’t verify your identity. Contact support for assistance.
- Stripe Terms of Service acceptance is required for this transaction. | Depends on the error message | Follow the error message to complete or retry verification. If the message directs the customer to support, ask them to contact Stripe support. |
| `crypto_onramp_wallet_address_invalid` | The wallet address isn’t valid for the specified network. | The wallet address provided isn’t a valid address for the {network} network. | Yes | Ask the customer to provide a valid wallet address for the selected network. |
| `crypto_onramp_wallet_addresses_not_all_networks_supported` | One or more networks in `transaction_details.wallet_addresses` aren’t in `transaction_details.supported_destination_networks`. | One or more networks in `transaction_details.wallet_addresses` aren’t in `transaction_details.supported_destination_networks`. | Yes | Remove wallet addresses for unsupported networks, or add those networks to `supported_destination_networks`. |
| `zerohash_api_error` | An error occurred while processing the crypto onramp request. Try again. | We couldn’t process the crypto onramp request. Try again. | No | Retry with exponential backoff. Contact Stripe support if the error continues. |