Processor error code mapping
Smart Retry is an intelligent optimization engine designed to maximize transaction success rates. Leveraging an advanced AI model, the system analyzes error codes returned from payment processors to determine the root cause of failure in real-time.
Upon receiving an error, the system classifies the transaction as either Non-Retryable or Retryable. If an error is deemed retryable, the AI dynamically selects the optimal recovery strategy from the following:
| Category | Example |
|---|---|
| Cascading retry | Refused, System malfunction, Processing temporarily unavailable |
| Step-up retry | Step-up retry |
| Clear PAN retry | Invalid cryptogram, Network token not supported, Payment token expired |
| Network retry | Transaction not permitted on this network, Invalid card for selected network, Function not supported |
To illustrate the classification process, the following tables lists few sample Stripe error codes and how our AI model categorizes them into Retryable versus Non-Retryable workflows.
Error codes categorize as Retryable :
| code | message |
|---|---|
| fraudulent | The payment was declined because Stripe suspects that it's a fraudulent. |
| payment_method_unexpected_state | The 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_invalid_parameter_testmode | The 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. |
| parameter_unknown | parameter_unknown |
| lock_timeout | This 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. |
| 500 | internal_server_error |
| payment_intent_invalid_parameter | One 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. |
| forwarding_api_upstream_connection_error | Stripe didn't receive a response from the destination endpoint. This typically indicates a problem with the destination endpoint, rather than with Stripe. |
| payment_method_unactivated | The operation can't be performed because the payment method used hasn't been activated. Activate the payment method in the Dashboard, then try again. |
| parameter_invalid_empty | One or more required values weren't provided. Make sure requests include all required parameters. |
| bitcoin_upgrade_required | This method for creating Bitcoin payments isn't supported anymore. Upgrade your integration to use Sources instead. |
| authentication_required | The 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. |
| partner_generic_decline | The payment provider has declined the payment |
| payment_method_unactivated | The operation cannot be performed as the payment method used has not been activated. Activate the payment method in the Dashboard, then try again. |
| partner_high_risk_customer | The payment provider labeled this customer as high risk |
| parameter_invalid_empty | One or more required values were not provided. Make sure requests include all required parameters. |
| call_issuer | The card was declined for an unknown reason. |
| fraudulent | The payment was declined because Stripe suspects that it's fraudulent. |
Error codes categorize as Non-Retryable :
| Error Code | Description / Message |
|---|---|
| card_decline_rate_limit_exceeded | This card has been declined too many times. You can try to charge this card again after 24 hours. We suggest reaching out to your customer to make sure they’ve entered all of their information correctly and that there are no issues with their card. |
| account_closed | The customer’s bank account has been closed. |
| invalid_cvc | The card’s security code is invalid. Check the card’s security code or use a different card. |
| acss_debit_session_incomplete | The ACSS debit session isn’t ready to transition to complete status yet. Try the request again later. |
| incorrect_number | The card number is incorrect. Check the card’s number or use a different card. |
| invalid_expiry_month | The card's expiration month is incorrect. |
| insufficient_funds | The customer’s account has insufficient funds to cover this payment. |
| card_declined | Your card does not support this type of purchase. |
| invalid_expiry_year | The card’s expiration year is incorrect. Check the expiration date or use a different card. |
| card_not_supported | The card doesn’t support this type of purchase. |
| pin_try_exceeded | The allowable number of PIN tries was exceeded. |
| pickup_card | The customer can’t use this card to make this payment (it’s possible it was reported lost or stolen). |