Stripe error code: card_declined
The card was declined by the issuer. `card_declined` is an error code, not a decline code — the reason for the decline is in the `decline_code` attribute on the same error, and that is the value you actually need to look up.
Retrying the same request will fail the same way.
What it means
Stripe documents this as: "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." This is the single most misread value in the Stripe API. Integrators see card_declined, search for it in the decline-code table, find nothing that explains their case, and conclude the documentation is incomplete. It is not — they are one field away. Read error.decline_code, not error.code, when you want the reason.
Common causes
- Any issuer decline at all. This code is the wrapper, so it appears for insufficient funds, do-not-honour, a stolen card and everything else alike.
- A Stripe Radar rule or Adaptive Acceptance blocking the payment, which surfaces as a decline with `generic_decline`.
- A test card that is designed to decline being used in test mode, which gives `testmode_decline`.
How to fix it
- Read `error.decline_code` and branch on that. `error.code` will be `card_declined` for every issuer decline and so cannot distinguish between them.
- Check `error.advice_code` too where present — Stripe sets it on issuer declines with a suggested next step, such as whether a retry is worth attempting.
- Show the customer a generic message regardless of the decline code. Several codes — `fraudulent`, `lost_card`, `stolen_card` — must not be reported specifically, and having one message for all of them is simpler than maintaining the exceptions.
- Do not treat every `card_declined` as retryable. Look the decline code up and let its severity drive whether you retry at all.
Tools that help
Frequently asked questions
- Why can I not find card_declined in the decline code table?
- Because it is not in it, and it never was. `card_declined` belongs to the error-code table; the decline-code table lists the values that appear in `decline_code`. They are two separate enumerations on two separate attributes of the same error object.
- What HTTP status does a card decline return?
- 402 Payment Required, with a `card_error` type. That is distinct from a 400, which means your request was malformed — a declined card is a well-formed request that the issuer refused.