Private preview
Crypto onramp error codes Private preview
Learn about crypto onramp error codes.
Some crypto onramp API 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 applicable tax or partner terms declaration is available. | No CRS or the related setting declaration is available. No partner terms declaration exists for declaration type {declaration_type} in region {region}. | 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 /the relevant part of the product 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 or the returned error message to see which values were not correct. | Invalid value for KYC field: {param} {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 /the relevant part of the product for an integration with no beta header, or beta v1. Use /the relevant part of the product 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 partner terms declaration is invalid. The user has already accepted this partner terms declaration. 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 the related setting declaration. | Submit a tax attestation before confirming the CRS or the related setting 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. Sorry, the quote expired while processing your payment. Please try again. | 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. The crypto onramp service is experiencing high request volume. Please try again later. 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. We’re unable to continue with your purchase. | 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. |