card_velocity_exceeded: what this Stripe decline code means and why pacing is the whole fix
lane: retry_gentlecard_velocity_exceededThe customer has exceeded the balance, credit limit, or transaction amount limit available on their card. Stripe's suggested next step is for the customer to contact their card issuer for more information.
What it means
A ceiling on the card was reached. Which ceiling, the code doesn't say: Stripe's description spans the balance, the credit limit and the transaction amount limit, and issuers also use this code for caps on how many transactions a card can make in a window. The safe reading is that the card ran into a limit somebody configured. Limits differ from most decline causes in the way that matters here: they are windowed, and when the window moves, the ceiling comes back.
The configurations come from every direction. Cardholders set per-merchant and per-period caps in banking apps. Issuers run velocity rules that treat a burst of transactions as a testing pattern. Corporate and prepaid programmes ship with ceilings by design. And one source is closer to home: attempts from your own retry system count like anyone else's transactions, so a burst of reattempts can create or extend the very condition it is responding to.
That last point is the page's whole lesson. For most declines a retry is a neutral question asked again. For this one, each attempt inside the same window pushes against the limit that produced the decline, so the useful move is to stop contributing and return after the window has had a chance to move. Nobody outside the issuer knows where the window's edges are.
Keep it separate from card_decline_rate_limit_exceeded, which looks similar and comes from the other side of the network. That one is Stripe refusing further attempts on a card that has been declined too many times, Stripe protecting the card from you. card_velocity_exceeded is the issuer's own ceiling, and it can fire on the first attempt you ever made, because other activity filled the window before you arrived.
Why it happens
Cardholder spending controls
Banking apps let cardholders cap spending per merchant or per period, and a renewal landing on the wrong side of a cap fails as a limit rather than as a judgement about you.
Issuer velocity rules
A run of transactions in a short window resembles card testing, and issuers cap throughput as a defence. The individual charges can all be legitimate; the pattern is what gets declined.
Programme ceilings
Corporate cards, prepaid cards and virtual card products ship with configured limits by design. The card behaves normally right up to the ceiling and declines cleanly past it.
A per-transaction cap
Stripe's description includes the transaction amount limit, so a single charge above the card's maximum fails on its own, with no window involved.
Your own retries
Reattempts count like transactions because they are transactions. A retry burst after an unrelated decline can trip a velocity limit, at which point the recovery mechanism has become the disease.
Common mistakes
Retrying into the same window
The decline says a window is full. Immediate reattempts fill it further and can keep the condition alive past its natural end. Of every code in this table, this is the one where fast retries are most directly self-defeating.
Reading it as an empty account
Stripe's description mentions balance, but a velocity decline is routinely a card with money behind it and a cap in front of it. An email implying the customer is out of funds mis-describes their situation and your problem.
Swapping the card by reflex
A different card does bypass the ceiling, and for a permanently capped card it is the right ask. As a first automated response it trades a working card for friction, when the condition often clears by itself once the window moves.
Missing your own fingerprints
If this code clusters after your retry bursts, across unrelated customers, the velocity being exceeded is yours. The fix is pacing on your side rather than new cards on theirs.
How Lirova handles it
Lirova routes card_velocity_exceeded to retry_gentle, and the fit is unusually literal. The gentle lane is about spacing attempts, nothing more, and spacing is the entire treatment for a velocity condition: the ceiling sits inside a window only the issuer can see, so the job is to stop contributing to it and ask again after it has had a chance to move. The schedule differs by decline reason and isn't stated here. An advice code from the issuer, when one arrives, outranks the lane.
FAQ
What does card_velocity_exceeded mean?
A limit on the card was reached. Stripe's description spans the balance, the credit limit and the transaction amount limit, and issuers also use the code for caps on how many transactions a card can make in a window. Which ceiling was hit is not disclosed.
Does card_velocity_exceeded mean the customer has no money?
Often not. The code covers configured ceilings as much as funds: spending controls the cardholder set, programme limits on corporate and prepaid cards, issuer velocity rules. The balance behind the card can be healthy while a cap in front of it does the declining.
Should I retry a card_velocity_exceeded decline?
Yes, with real space between attempts. The condition is windowed, and attempts inside the same window push against the limit that caused the decline. If the issuer attached an advice code, read it before anything else.
Is card_velocity_exceeded the same as card_decline_rate_limit_exceeded?
No. card_velocity_exceeded is the issuer's ceiling on the card's activity, and it can fire on your first attempt if other activity filled the window. card_decline_rate_limit_exceeded is Stripe refusing further attempts on a card that has been declined too many times, which makes it a comment on the attempts rather than on the card.
Related codes
Updated 2026-09-01