stripe

Stripe API Error Codes

Error and decline codes returned by the Stripe payment API. Decline codes appear in the decline_code field of a card_error and indicate why a card issuer declined the charge.

33 codes

references stripe.com/docs/error-codes stripe.com/docs/declines/codes

· All codes 33 codes

api_connection_error API Connection Error The Stripe library could not establish a network connection to Stripe's servers, for example due to a local network problem or a TLS handshake failure. Retry the request after confirming network connectivity.
api_error API Error An error occurred internally on Stripe's servers. These are rare; Stripe's status page tracks incidents. Retrying the request, ideally with an idempotency key, is usually safe.
authentication_error Authentication Error Stripe could not authenticate the request because the API key provided was invalid, missing, or revoked. Check that the correct secret key for the target environment (test or live) is being used.
authentication_required Authentication Required The card was declined because the transaction requires authentication (3D Secure / SCA). Retry the payment using Stripe's confirmCardPayment to trigger the authentication challenge instead of a server-side charge.
call_issuer Call Issuer The card has been declined for an unknown reason and the issuer is asking the cardholder to call them directly to resolve it.
card_declined Card Declined The card has been declined for an unspecified reason. The specific reason is usually in the decline_code field. Ask the customer to contact their card issuer or try a different payment method.
card_velocity_exceeded Card Velocity Exceeded The customer has exceeded the balance, credit limit, or velocity limit on their card. Ask the customer to use a different card or wait before retrying.
currency_not_supported Currency Not Supported The card does not support the specified currency. Ask the customer to try a different payment method that supports the currency.
do_not_honor Do Not Honor The issuing bank declined the payment without specifying a reason. This is a generic issuer decline. Ask the customer to contact their bank or use a different payment method.
duplicate_transaction Duplicate Transaction A transaction with identical amount and details was submitted very recently on the same card, and the issuer has flagged it as a likely duplicate. If the charge is genuinely separate, wait before retrying.
expired_card Expired Card The card has expired. Ask the customer to use a different card or update their payment method with a valid expiry date.
fraudulent Fraudulent Stripe's fraud prevention system (Radar) suspects this payment is fraudulent and blocked it. Do not reveal this reason to the customer. This code is also returned when a Stripe Radar rule blocks the payment.
generic_decline Generic Decline The card has been declined for an unspecified reason and no more detailed decline code is available. Ask the customer to contact their card issuer for more information or try a different payment method.
idempotency_error Idempotency Error The request reused an idempotency key with parameters that differ from the original request. Use a new idempotency key for each distinct operation.
incorrect_cvc Incorrect CVC The card's security code (CVC/CVV) is incorrect. Ask the customer to re-enter their card details, paying close attention to the security code printed on the card.
incorrect_number Incorrect Card Number The card number is incorrect. Ask the customer to re-enter their card number carefully. Stripe validates the Luhn checksum client-side, so this usually means a transcription error.
insufficient_funds Insufficient Funds The card has insufficient funds to complete the transaction. Ask the customer to use a different card or payment method, or to add funds to their account before retrying.
invalid_account Invalid Account The card, or the account it is connected to, is not valid. Ask the customer to contact their card issuer to check that the account is set up correctly.
invalid_amount Invalid Amount The payment amount is invalid, or exceeds the limit allowed by the card issuer for this transaction type.
invalid_cvc Invalid CVC The CVC supplied is not a valid format for the card. This differs from incorrect_cvc, which means a correctly formatted CVC simply did not match the card on file.
invalid_expiry_month Invalid Expiry Month The card's expiration month is invalid. Ask the customer to check and re-enter the expiration date. Valid values are 1–12.
invalid_expiry_year Invalid Expiry Year The card's expiration year is invalid. Ask the customer to check and re-enter the expiration date.
invalid_request_error Invalid Request Error The request to the Stripe API contained invalid parameters. Check the error's param field to identify which parameter is invalid. This is a programming error in the integration that should be corrected in code, not surfaced to the end user.
issuer_not_available Issuer Not Available The card issuer could not be reached in time, so the payment could not be authorised. Retrying after a short delay often succeeds.
lost_card Lost Card The payment was declined because the card has been reported lost. Do not reveal this specific reason to the customer. Ask them to use a different payment method.
pickup_card Pickup Card The card cannot be used for this payment, typically because the issuer has flagged it as lost or stolen. Ask the customer to contact their card issuer.
processing_error Processing Error An error occurred while the card issuer or network processed the payment. Retrying the same request, possibly after a short delay, often succeeds.
rate_limit Rate Limit Too many requests hit the Stripe API too quickly. Implement exponential backoff with jitter when retrying API calls. If rate limiting occurs frequently, review request patterns or contact Stripe to discuss limits.
restricted_card Restricted Card The card cannot be used for this payment, typically because the issuer has flagged it as lost or stolen, or it has restrictions that prevent this type of purchase. Ask the customer to contact their card issuer.
stolen_card Stolen Card The payment was declined because the card has been reported stolen. Do not reveal this specific reason to the customer. Ask them to use a different payment method.
transaction_not_allowed Transaction Not Allowed The card does not permit this type of transaction. Ask the customer to contact their card issuer to find out why the purchase was rejected.
try_again_later Try Again Later The card has been declined for an unknown reason and the issuer suggests retrying the payment after some time has passed.
withdrawal_count_limit_exceeded Withdrawal Count Limit Exceeded The customer has exceeded the balance, credit limit, or maximum number of transactions available on their card. Ask the customer to use a different payment method.