Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Essentials
SDKs
API
    API v2
    API keys
    Stripe-Context header
    Daily changelog
    Rate limits
    Automated testing
    Metadata
    Expanding responses
    Pagination
    Domains and IP addresses
    Search
    Localisation
    Error handling
    Error codes
Testing
Stripe CLI
Tools
Workbench
Developers Dashboard
Stripe Shell
Stripe for Visual Studio Code
Features
Workflows
Event Destinations
Stripe health alertsFile uploads
AI solutions
Agent toolkit
Security and privacy
Security
Privacy
Extend Stripe
Build Stripe apps
Use apps from Stripe
Partners
Partner ecosystem
Partner certification
HomeDeveloper resourcesAPI

Error codes

Learn more about error codes and how to resolve them.

Reviewing errors

Stripe logs every successful or failed API request your integration makes. Use Workbench to review errors and monitor your integration.

Some Errors include an error code – a short string with a brief explanation. These codes can help you handle errors, such as payment errors.

The following is a list of Stripe error codes, their descriptions, and occasionally information about how to resolve them. Every Error object links to this list in its doc_url attribute. You can also trigger certain specific error codes for testing purposes.

Error codeDescription
account_closedThe customer’s bank account has been closed.
account_country_invalid_addressThe country of the business address provided doesn’t match the country of the account. Businesses must be located in the same country as the account.
account_invalidThe account ID provided as a value for the Stripe-Account header is invalid. Check that your requests are specifying a valid account ID.
account_error_country_change_requires_additional_stepsYour account has already onboarded as a Connect platform. Changing your country requires additional steps. Contact Stripe support for more information.
account_number_invalidThe bank account number provided is invalid (for example, missing digits). Bank account information varies from country to country. We recommend creating validations in your entry forms based on the bank account formats we provide.
amount_too_largeThe specified amount is greater than the maximum amount allowed. Use a lower amount and try again.
amount_too_smallThe specified amount is less than the minimum amount allowed. Use a higher amount and try again.
api_key_expiredThe API key provided has expired. Obtain your current API keys from the Dashboard and update your integration to use them.
authentication_requiredThe payment requires authentication to proceed. If your customer is off session, notify your customer to return to your application and complete the payment. If you provided the error_on_requires_action parameter, then your customer should try another card that doesn’t require authentication.
balance_insufficientThe transfer or payout couldn’t be completed because the associated account doesn’t have a sufficient balance available. Create a new transfer or payout using an amount less than or equal to the account’s available balance.
balance_invalid_parameterInvalid parameter was provided in the balance method object. Check our API documentation or the returned error message for more context.
bank_account_bad_routing_numbersThe bank account is known to not support the currency in question.
bank_account_declinedThe bank account provided can’t be used to charge, either because it isn’t verified yet or it isn’t supported.
bank_account_existsThe bank account provided already exists on the specified Customer object. If the bank account should also be attached to a different customer, include the correct customer ID when making the request again.
bank_account_verification_failedThe bank account can’t be verified, either because the microdeposit amounts provided don’t match the actual amounts, or because verification has failed too many times.
bank_account_unusableThe bank account provided can’t be used. A different bank account must be used.
bank_account_unverifiedYour Connect platform is attempting to share an unverified bank account with a connected account.
capture_charge_authorization_expiredThe charge can’t be captured as the authorisation has expired. Refer to the payment method’s documentation to learn more.
capture_unauthorized_paymentThe charge you’re attempting to capture has not been authorised for capturing payment.
card_decline_rate_limit_exceededThis card has been declined too many times. You can try to charge this card again after 24 hours. We suggest contacting your customer to make sure they’ve entered all of their information correctly and that there are no issues with their card.
charge_already_capturedThe charge you’re attempting to capture has already been captured. Update the request with an uncaptured charge ID.
charge_already_refundedThe charge you’re attempting to refund has already been refunded. Update the request to use the ID of a charge that has not been refunded.
charge_disputedThe charge you’re attempting to refund has been charged back. See Disputes to learn how to respond to the dispute.
charge_exceeds_source_limitThis charge would cause you to exceed your rolling-window processing limit for this source type. Retry the charge later, or contact us to request a higher processing limit.
charge_exceeds_transaction_limitThis charge would cause you to exceed your processing limit for this payment type. Contact us to request a higher processing limit.
charge_invalid_parameterOne or more provided parameters was not allowed for the given operation on the Charge. See our API reference or the returned error message to see which values weren’t correct for that Charge.
country_unsupportedYour platform attempted to create a custom account in a country that’s not yet supported. Make sure that users can only sign up in countries supported by custom accounts.
country_code_invalidThe country code provided was invalid.
coupon_expiredThe coupon provided for a subscription or order has expired. Either create a new coupon, or use an existing one that’s valid.
customer_max_subscriptionsThe maximum number of subscriptions for a customer has been reached. Contact us if you’re receiving this error.
customer_max_payment_methodsThe maximum number of PaymentMethods for this Customer has been reached. Either detach some PaymentMethods from this Customer or proceed with a different Customer.
customer_tax_location_invalidThe customer address is missing or not valid for tax purposes. Make sure to provide a country as a two-letter ISO code and also a postal_code, at minimum. See how to collect customer addresses.
shipping_address_invalidThe shipping address information can’t be used to accurately determine tax rates. Verify that address fields such as zip or postal code, state, region, or province have been added correctly.
billing_invalid_mandateThe Subscription or Invoice attempted payment on a PaymentMethod without an active mandate. To create Subscription or Invoice payments with this PaymentMethod, it must be confirmed on-session with a PaymentIntent or SetupIntent first.
email_invalidThe email address is invalid (for example, not properly formatted). Check that the email address is properly formatted and only includes allowed characters.
idempotency_key_in_useThe idempotency key provided is currently being used in another request. This occurs if your integration is making duplicate requests simultaneously.
financial_connections_account_inactiveData can’t be refreshed on inactive Financial Connections accounts.
financial_connections_no_successful_transaction_refreshTransaction data can only be retrieved for accounts that have at least one successful transaction refresh.
instant_payouts_unsupportedInstant Payouts are not available for this request. See Instant payouts for detailed requirements and supported configurations.
instant_payouts_limit_exceededYou’ve reached your daily processing limits for Instant Payouts.
instant_payouts_config_disabledThis connected account isn’t eligible for Instant Payouts. Ask the platform to enable Instant Payouts.
payouts_limit_exceededYou’ve reached your daily processing limits for this payout type.
insufficient_fundsThe customer’s account has insufficient funds to cover this payment.
invalid_charactersThis value provided to the field contains characters that are unsupported by the field.
invalid_card_typeThe card provided as an external account isn’t supported for payouts. Provide a non-prepaid debit card instead.
invoice_no_customer_line_itemsAn invoice can’t be generated for the specified customer as there are no pending invoice items. Verify that the correct customer is being specified or create any necessary invoice items first.
invoice_on_behalf_of_not_editableYou can’t update the on_behalf_of property of an invoice after the invoice has been assigned a number.
invoice_no_payment_method_typesAn invoice can’t be finalised because there are no payment method types available to process the payment. Your invoice template settings or the invoice’s payment_settings might be restricting which payment methods are available, or you might need to activate more payment methods in the Dashboard.
invoice_no_subscription_line_itemsAn invoice can’t be generated for the specified subscription as there are no pending invoice items. Verify that the correct subscription is being specified or create any necessary invoice items first.
invoice_not_editableThe specified invoice can no longer be edited. Instead, consider creating additional invoice items that will be applied to the next invoice. You can either manually generate the next invoice or wait for it to be automatically generated at the end of the billing cycle.
invoice_payment_intent_requires_actionThis payment requires additional user action before it can be completed successfully. Payment can be completed using the PaymentIntent associated with the invoice.
invoice_upcoming_noneThere is no upcoming invoice on the specified customer to preview. Only customers with active subscriptions or pending invoice items have invoices that can be previewed.
no_accountThe bank account couldn’t be located.
debit_not_authorizedThe customer has notified their bank that this payment was unauthorized.
bank_account_restrictedThe customer’s account can’t be used with the payment method.
out_of_inventoryOne or more line item(s) are out of stock. If more stock is available, update the inventory’s orderable quantity and try again.
parameter_invalid_emptyOne or more required values weren’t provided. Make sure requests include all required parameters.
parameter_invalid_integerOne or more of the parameters requires an integer, but the values provided were a different type. Make sure that only supported values are provided for each attribute. Refer to the API reference to see the type of data each attribute supports.
parameter_invalid_string_blankOne or more values provided only included whitespace. Check the values in your request and update any that contain only whitespace.
parameter_invalid_string_emptyOne or more required string values is empty. Make sure that string values contain at least one character.
parameter_missingOne or more required values are missing. Check our API documentation to see which values are required to create or modify the specified resource.
parameter_unknownThe request contains one or more unexpected parameters. Remove these and try again.
parameters_exclusiveTwo or more mutually exclusive parameters were provided. See the API reference or the returned error message to see which values are permitted when creating or modifying the specified resource.
acss_debit_session_incompleteThe ACSS debit session isn’t ready to transition to complete status yet. Try the request again later.
payment_method_billing_details_address_missingThe PaymentMethod’s billing details is missing address details. Update the missing fields and try again.
payment_method_unsupported_typeThe API only supports payment methods of certain types.
payment_method_customer_declineThe customer didn’t approve the payment. Provide a new payment method to attempt to fulfil this intent again.
payment_method_microdeposit_verification_attempts_exceededYou’ve exceeded the number of allowed verification attempts.
intent_invalid_stateIntent isn’t in the state that’s required to perform the operation.
intent_verification_method_missingIntent doesn’t have verification method specified in its PaymentMethodOptions object.
payment_method_invalid_parameterInvalid parameter was provided in the payment method object. See the API reference or the returned error message for more context.
payment_method_invalid_parameter_testmodeThe parameter provided for payment method isn’t allowed to be used in testmode. See the API reference or the returned error message for more context.
payment_method_provider_timeoutThe payment method failed due to a timeout. Check the last_payment_error or last_setup_error property on the PaymentIntent or SetupIntent respectively for more details, and provide a new payment method to attempt to fulfil this intent again.
payment_method_provider_declineThe payment or setup attempt was declined by the issuer or customer. Check the last_payment_error or last_setup_error property on the PaymentIntent or SetupIntent respectively for more details, and provide a new payment method to attempt to fulfil this intent again.
payment_method_microdeposit_verification_amounts_mismatchThe amounts provided don’t match the amounts that were sent to the bank account.
payment_method_microdeposit_verification_descriptor_code_mismatchThe verification code provided doesn’t match the one sent to the bank account.
payment_method_microdeposit_verification_amounts_invalidYou must provide exactly two micro-deposit amounts.
payment_method_microdeposit_failedMicrodeposits were failed to be deposited into the customer’s bank account. Check the account, institution, transit numbers, and currency type.
payment_method_microdeposit_verification_timeoutPayment method should be verified with microdeposits within the required period.
payment_method_bank_account_already_verifiedThis bank account has already been verified.
payment_method_bank_account_blockedThis bank account has failed verification in the past and can’t be used. Contact us if you want to attempt to use these bank account credentials.
payment_method_unactivatedThe operation can’t be performed because the payment method used hasn’t been activated. Activate the payment method in the Dashboard, then try again.
payment_method_currency_mismatchThe currency specified doesn’t match the currency for the attached payment method. A payment can only be created for the same currency as the corresponding payment method.
payment_method_unexpected_stateThe provided payment method’s state was incompatible with the operation you were trying to perform. Confirm that the payment method is in an allowed state for the given operation before attempting to perform it.
payment_method_not_availableThe payment processor for the provided payment method is temporarily unavailable. Try a different payment method or retry later with the same payment method.
payment_intent_unexpected_stateThe PaymentIntent’s state was incompatible with the operation you were trying to perform.
payment_intent_incompatible_payment_methodThe PaymentIntent expected a payment method with different properties than what was provided.
payment_intent_invalid_parameterOne or more provided parameters was not allowed for the given operation on the PaymentIntent. See the API reference or the returned error message to see which values weren’t correct for that PaymentIntent.
payment_intent_mandate_invalidThe provided mandate is invalid and can’t be used for the payment intent.
setup_intent_mandate_invalidThe provided mandate is invalid and can’t be used for the setup intent.
invalid_mandate_reference_prefix_formatThe provided prefix used to generate the mandate reference is invalid.
payment_intent_konbini_rejected_confirmation_numberThe confirmation_number provided in payment_method_options[konbini] was rejected by the processing partner at time of PaymentIntent confirmation.
payment_intent_authentication_failureThe provided payment method has failed authentication. Provide a new payment method to attempt to fulfil this PaymentIntent again.
payment_intent_payment_attempt_failedThe latest payment attempt for the PaymentIntent has failed. See the last_payment_error property on the PaymentIntent for more details, and provide a new payment method to attempt to fulfil this PaymentIntent again.
payment_intent_payment_attempt_expiredThe latest payment attempt for the PaymentIntent has expired. Check the last_payment_error property on the PaymentIntent for more details, and provide a new payment method to attempt to fulfil this PaymentIntent again.
setup_intent_setup_attempt_expiredThe latest setup attempt for the SetupIntent has expired. Check the last_setup_error property on the SetupIntent for more details, and provide a new payment method to attempt to complete this SetupIntent again.
payment_intent_amount_reconfirmation_requiredYou provided information that changed the total amount of your PaymentIntent. Show the updated amount to your customer and try again.
payment_intent_automatic_tax_incompleteWhen automatic_tax[enabled]=true, you must provide enough location information to accurately determine tax rates for the buyer to confirm the PaymentIntent and collect taxes.
payment_intent_action_requiredThe provided payment method requires customer actions to complete, but error_on_requires_action was set. To add this payment method to your integration, we recommend that you first upgrade your integration to handle actions.
platform_account_requiredOnly Stripe Connect platforms can work with other accounts. You can set up a Stripe Connect platform in the Dashboard.
setup_intent_authentication_failureThe provided payment method has failed authentication. Provide a new payment method to attempt to fulfil this SetupIntent again.
setup_intent_unexpected_stateThe SetupIntent’s state was incompatible with the operation you were trying to perform.
setup_intent_invalid_parameterOne or more provided parameters was not allowed for the given operation on the SetupIntent. See the API reference or the returned error message to see which values weren’t correct for that SetupIntent.
setup_attempt_failedThe latest setup attempt for the SetupIntent has failed. Check the last_setup_error property on the SetupIntent for more details, and provide a new payment method to attempt to set it up again.
status_transition_invalidThe requested status transition isn’t valid.
payouts_not_allowedPayouts have been disabled on the connected account. Check the connected account’s status to see if any additional information needs to be provided, or if payouts have been disabled for another reason.
platform_api_key_expiredThe API key provided by your Connect platform has expired. This occurs if your platform has either generated a new key or the connected account has been disconnected from the platform. Obtain your current API keys from the Dashboard and update your integration, or contact the user and reconnect the account.
postal_code_invalidThe postal code provided was incorrect.
refer_to_customerThe customer has stopped the payment with their bank. Contact them for details and to arrange payment.
resource_already_existsA resource with a user-specified ID (for example, plan or coupon) already exists. Use a different, unique value for id and try again.
resource_missingThe ID provided isn’t valid. Either the resource doesn’t exist, or an ID for a different resource has been provided.
routing_number_invalidThe bank routing number provided is invalid.
stripe_tax_inactiveStripe Tax hasn’t been activated on your account. See the setup documentation to get started.
clearing_code_unsupportedThe clearing code provided isn’t supported.
secret_key_requiredThe API key provided is a publishable key, but a secret key is required. Obtain your current API keys from the Dashboard and update your integration to use them.
state_unsupportedOccurs when providing the legal_entity information for a US custom account, if the provided state isn’t supported. (This is mostly associated states and territories.)
tax_id_invalidThe tax ID number provided is invalid (for example, missing digits). Tax ID information varies from country to country, but must be at least nine digits.
tax_id_prohibitedA tax identifier may not be provided on this payment method as it isn’t required.
terminal_location_country_unsupportedTerminal is currently only available in some countries. Locations in your country can’t be created in live mode.
terminal_reader_offlineReader is currently offline. Ensure the reader is powered on and connected to the internet before retrying your request. See the integration guide for details on how to handle this error.
terminal_reader_timeoutThere was a timeout when sending this command to the reader. See the integration guide for details on how to handle this error.
terminal_reader_busyReader is currently busy processing another request. See the integration guide for details on how to handle this error.
terminal_reader_hardware_faultReader can no longer accept payments as an unrecoverable hardware fault has been detected. Contact Stripe support and provide your reader’s serial number for replacement.
terminal_reader_invalid_location_for_activationReader can’t be activated in the currently registered Location. Register the reader to a new Location. See Manage locations for more information.
terminal_reader_invalid_location_for_paymentReader can’t take payments in the currently registered Location. Register the reader to a new Location. See Manage locations for more information.
tls_version_unsupportedYour integration is using an older version of TLS that’s unsupported. You must be using TLS 1.2 or above.
token_already_usedThe token provided has already been used. You must create a new token before you can retry this request.
token_in_useThe token provided is currently being used in another request. This occurs if your integration is making duplicate requests simultaneously.
transfers_not_allowedThe requested transfer can’t be created. Contact us if you’re receiving this error.
transfer_source_balance_parameters_mismatchWhen creating a Transfer, the payments parameter in source_balance shouldn’t be passed in when balance type is set to issuing.
url_invalidThe URL provided is invalid.
not_allowed_on_standard_accountTransfers and payouts on behalf of a Standard connected account aren’t allowed.
lock_timeoutThis object can’t be accessed right now because another API request or Stripe process is currently accessing it. If you see this error intermittently, retry the request. If you see this error frequently and are making multiple concurrent requests to a single object, make your requests serially or at a lower rate. See the Object lock timeouts for more details.
cardholder_phone_number_requiredYou must have a phone_number on file for Issuing Cardholders who will be creating EU cards. You can’t create EU cards without a phone_number on file for the cardholder. See the 3DS Secure for more details.
return_intent_already_processedYou can’t confirm this refund as it’s already processed.
refund_disputed_paymentYou can’t refund a disputed payment.
progressive_onboarding_limit_exceededProgressive onboarding limit has been reached for the platform.
forwarding_api_inactiveThe Vault and Forward API is currently not accessible with this account and configuration. Contact us if you’re receiving this error.
forwarding_api_invalid_parameterInvalid parameter was provided in the Vault and Forward API. Check our API documentation or the returned error message for more context.
forwarding_api_upstream_connection_timeoutThe request to the destination endpoint timed out. This typically indicates a problem with the destination endpoint, rather than with Stripe.
forwarding_api_upstream_connection_errorStripe didn’t receive a response from the destination endpoint. This typically indicates a problem with the destination endpoint, rather than with Stripe.
forwarding_api_retryable_upstream_errorThe destination endpoint appears to be offline or unresponsive, preventing Stripe from completing the request. Retry the request later.
forwarding_api_upstream_errorThe destination endpoint appears to be offline or unresponsive, preventing Stripe from completing the request. You might want to investigate the state of the request on the third party because bytes might have been sent and the third-party state could be indeterminate.
alipay_upgrade_required This method for creating Alipay payments isn’t supported anymore. Upgrade your integration to use Sources instead.
bitcoin_upgrade_required This method for creating Bitcoin payments isn’t supported anymore. Upgrade your integration to use Sources instead.
card_declined The card has been declined. When a card is declined, the error returned also includes the decline_code attribute with the reason why the card was declined. To learn more, see decline codes.
charge_expired_for_capture The charge can’t be captured because the authorization has expired. Authorization and capture charges must be captured within a set number of days (7 by default).
expired_card The card has expired. Check the expiration date or use a different card.
incorrect_address The card’s address is incorrect. Check the card’s address or use a different card.
incorrect_cvc The card’s security code is incorrect. Check the card’s security code or use a different card.
incorrect_number The card number is incorrect. Check the card’s number or use a different card.
incorrect_zip The card’s postal code is incorrect. Check the card’s postal code or use a different card.
invalid_tax_location The specified location is invalid. Check the Supported address formats for the address formats supported when calculating tax.
invalid_charge_amount The specified amount is invalid. The charge amount must be a positive integer in the smallest currency unit, and not exceed the minimum or maximum amount.
invalid_cvc The card’s security code is invalid. Check the card’s security code or use a different card.
invalid_expiry_month The card’s expiration month is incorrect. Check the expiration date or use a different card.
invalid_expiry_year The card’s expiration year is incorrect. Check the expiration date or use a different card.
invalid_number The card number is invalid. Check the card details or use a different card.
invalid_source_usage The source can’t be used because it isn’t in the correct state (for example, a charge request is trying to use a source with a pending, failed, or consumed status). Check the status of the source you’re attempting to use.
livemode_mismatch Test and live mode API keys, requests, and objects are only available within the corresponding mode.
missing Both a customer and source ID have been provided, but the source hasn’t been saved to the customer. To create a charge for a customer with a specified source, you must first save the card details.
processing_error An error occurred while processing the card. Try again later or with a different payment method.
product_inactive The product this SKU belongs to is no longer available for purchase.
rate_limit Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
sepa_unsupported_account Your account doesn’t support SEPA payments.
shipping_calculation_failed Shipping calculation failed because the information provided was either incorrect or couldn’t be verified.
sku_inactive The SKU is inactive and no longer available for purchase. Use a different SKU, or make the current SKU active again.
taxes_calculation_failed Tax calculation for the order failed.
testmode_charges_only Your account hasn’t been activated and can only make test charges. Activate your account in the Dashboard to begin processing live charges.
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access programme.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc