What is the difference between error code and decline code in Stripe?

The error code (such as card_declined) is set on the top-level error object and tells you the broad reason a request failed. The decline_code is a more specific reason the card issuer gave (such as insufficient_funds or do_not_honor) and is only present when error code is card_declined.

How should I handle a card_declined error?

Inspect the decline_code for the specific reason. For insufficient_funds or expired_card, ask the customer to use another card. For generic_decline or do_not_honor the issuer gave no detail, so prompt the customer to contact their bank. Never retry a hard decline automatically.

What does authentication_required mean?

authentication_required means the card requires 3D Secure (Strong Customer Authentication) before the payment can complete. Use the Payment Intents API and present the next_action so the customer can authenticate with their bank, then confirm the intent again.

Which Stripe errors are safe to retry?

Transient errors such as processing_error, rate_limit_error, or a 5xx api_error are safe to retry with idempotency keys and backoff. Decline codes like insufficient_funds, lost_card, or stolen_card are terminal and must not be retried — they require customer action or are fraud signals.

Is anything I search uploaded?

No. The full error index and the search run entirely in your browser. Nothing you type is sent to any server.

Stripe Error Codes Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

This is a searchable reference for Stripe error codes — the high-level error type, the specific code, and the card decline_code your integration receives when a charge or API call fails. Each entry explains what the code means and the recommended way to handle it, so you can show the right message to the customer and decide whether to retry.

How it works

Every Stripe error object has a type (such as card_error, invalid_request_error, api_error, authentication_error, or rate_limit_error) that tells you the broad class. Card-specific failures add a machine-readable code (for example card_declined, expired_card, incorrect_cvc). When code is card_declined, Stripe also sets a decline_code — the issuer’s specific reason — which is the most useful field for messaging the customer:

error.type        = card_error
error.code        = card_declined
error.decline_code = insufficient_funds

Branch on decline_code first when it exists, then code, then type. Soft issues like processing_error are retryable; hard issues like lost_card or stolen_card are fraud signals you must not retry and should treat generically in the UI to avoid tipping off fraudsters.

Tips and example

Map each code to a clear customer action rather than showing the raw string:

insufficient_funds   → "Your card has insufficient funds. Try another card."
expired_card         → "Your card has expired. Use a different card."
incorrect_cvc        → "The security code is incorrect. Check and retry."
authentication_required → trigger 3D Secure (Payment Intents next_action)
generic_decline / do_not_honor → "Your bank declined this. Please contact them."

Always pass an idempotency key when retrying transient errors so a network blip never double-charges a customer. Everything runs in your browser; nothing is uploaded.