How to read Stripe decline codes and what each failure needs

Stripe puts a decline code on every failed charge, and the mix of codes tells you what kind of recovery you need. An expired card needs the customer to give you a new one. A temporary shortfall may succeed on a later retry. Pull your own codes for the last year and read the top few. They will not match anyone else's.

Where do I find decline codes?

On the failed charge. Each failed charge carries a failure code, and Stripe's API returns it on the charge object. That is why my analysis asks for read access to charges and refunds. It counts the failed charges in the window and lists the five most common codes.

If you do not have access to the API, the same information is visible per payment in your dashboard, one at a time. For a count over a year, you want the export or the API.

Which codes show up most?

That depends entirely on your customers. In my synthetic sample report, for a fictional company, the top three were card_declined (180), generic_decline (178) and expired_card (167). I generated that data, so the numbers say nothing about your account. They show how the list appears in the report.

Notice what two of those three codes have in common: they are vague. card_declined and generic_decline tell you the bank refused the charge without telling you why. Do not build a theory on a vague code.

What does each kind of failure need?

I group failures by cause, because the cause decides the cure:

• Expired card. Retrying will not help. The customer has to give you a new card, so the only thing that works is asking them, ideally before the card expires.
• Over the limit or short of funds. Often temporary. A later retry may succeed once the account has refilled, so spacing retries over days is reasonable.
• Vague decline. Treat it as unknown. A retry might work, and a card-update message is the safe backup.

I do not have a magic retry schedule, and I would be wary of anyone who does without seeing your codes. What I can say is that one rule for every failure leaves money behind.

How do I turn codes into a plan?

1. Export failed charges for the last 365 days.
2. Count them by code and keep the top five.
3. For each, write one line: retry, ask for a new card, or unknown.
4. Compare the result with your recovery rate and the dollars lost, so you know which code is costing you the most, not only which is most common.

The last step matters. A rare code that hits your most expensive plans can cost more than a common one on a small plan. Count dollars as well as events. For the rate itself, see how to calculate a failed-payment recovery rate.

Can I prevent some failures?

Partly. Cards have expiry dates that Stripe knows, so a card-update email sent before the date removes some failures at the source. It is the cheapest recovery, because the customer is not in trouble yet. It does not cover cards replaced after fraud, a lost card or a change of bank. Those do not announce themselves. So pre-expiry emails reduce expired-card failures, they do not end them.

I describe the whole sequence in how to recover failed payments on Stripe subscriptions.

What should a message say for each cause?

Keep the language the same plain structure: what happened, the product and the amount, what will happen if nothing changes, and one link to a page that does only one thing, update the card. Send it from your own domain and in your voice, since a message from a sender the customer does not know looks like phishing. And do not attach a discount to a failed payment. A customer whose card failed did not ask for a lower price.

For a card that expired, say so. For a vague decline, say less: "your payment did not go through" is enough. Guessing the reason in the message can be wrong, and a wrong guess costs trust.

What can codes not tell me?

Why the bank said no, beyond the code. They also do not tell you whether the customer would have paid had you asked, or whether your emails helped. For that you need a test with a holdout group.

And remember the scope: my numbers cover Stripe only. A charge made through another processor does not appear.

How many codes should I track?

Five. My report lists the five most common codes for failed charges in the window, which is enough to see where the weight sits without drowning in detail. If the top three account for most of the failures, your plan can be three lines long. If the list is flat, with many codes of similar size, you probably cannot do better than a general sequence of retries and a card-update message.

Review the list a few times a year. Codes shift when your customer mix, pricing or payment methods change, and a plan written for last year's list may not fit this year's.

Do I need to do this by hand?

If you have a few hundred failed charges a year, a spreadsheet pivot by code is an afternoon. If you have thousands, the report does it for $490: a restricted read-only key, within 48 hours of my receiving it. It includes the top decline codes next to the recovery rate and the fix I would try first. See the synthetic sample to see where they appear.