A card can fail a DimeBox wallet in a few different moments - at initial funding, at a manual top-up, during an auto-reload attempt, or at a subscription renewal - and those moments aren't all the same failure, even though "declined" covers all of them loosely. It's worth separating what actually happens in each case, because the right response for an agent differs.
If the very first charge that would create or fund a wallet is declined, nothing gets created - there's no wallet with a balance to spend, no secret issued, nothing for an agent to authenticate with yet. This is the easiest case to handle: it fails before any API integration exists, so it's caught wherever you're setting up the wallet at /wallet, not inside a running agent.
This is the one that actually affects a running agent. If auto-reload's threshold triggers a top-up and the saved card is declined - expired, over its limit, flagged by the issuer - the wallet doesn't get credited, and it keeps operating on whatever balance it had when the threshold tripped. If that balance was already low enough to trigger the reload in the first place, the wallet can run out entirely a few calls later, and subsequent paid calls using that wallet's secret stop succeeding the same way they would with an exhausted balance and no auto-reload at all. See Auto-Reload for Agent Wallets for the mechanism this interrupts.
Similar outcome, different trigger: a subscription's recurring charge fails at the scheduled billing date instead of at a balance threshold, so the wallet simply doesn't get that period's credit. It's otherwise the same situation - whatever balance existed keeps getting spent down until either the card issue is resolved or the balance hits zero.
From the agent's side, none of these decline scenarios produce a special error of their own - they produce the same outcome as any other wallet-authentication failure on a paid route: the call doesn't succeed. An agent built to retry blindly on any failure will burn through retries without getting anywhere, which is the wrong response here just as it's the wrong response to a flat-out exhausted balance. Treat a sustained wallet-auth failure as a signal to stop the loop and surface it, not as a transient error worth retrying a few times and moving on.
A declined or exhausted-balance wallet is a funding problem - fix the card or top up, and it works again immediately. A frozen wallet is a different thing entirely: an intervention DimeBox applies in response to suspected abuse, not a payment failure on your end. What a Wallet Freeze Means covers that distinction and when it applies, because the two look similar from the outside - paid calls stop working - but have completely different causes and completely different remedies.
A declined charge, wherever it happens in this chain, never credits the wallet, and a wallet that never gets credited never ends up debited for calls it couldn't actually afford - paid routes simply stop authenticating once the balance (and any daily spend limit) is exhausted. That mirrors the same principle covered in Why DimeBox Never Charges for a Failed API Call: a failure, on either side of the payment, doesn't produce a charge.
Keep the card on file current, and build whatever monitoring makes sense for your setup - a daily balance check, an alert on repeated wallet-auth failures - rather than relying on the agent itself to notice and recover from a funding problem mid-task. A wallet running close to its daily spend limit (Setting Daily Spend Limits on an Autonomous Agent's Wallet) is worth watching for the same reason: both failure modes look identical to the calling code, and both need a human in the loop to actually resolve.
It might seem safer for a declined charge to just keep retrying on its own until it succeeds. In practice, a card that's declined once for being expired or over its limit is unlikely to succeed on an immediate retry, and hammering a card issuer with repeated attempts in a short window is exactly the kind of pattern that gets a card flagged for further scrutiny, making the underlying problem worse rather than better. That's why the better default, on both DimeBox's side and in how you design the agent calling it, is to fail clearly and let whoever manages the card decide when to fix it and try again - not to paper over a declined charge with blind retries that mostly just produce more declined attempts.
Before assuming abuse or a platform issue, the ordinary explanations cover almost every decline: an expired card, a card issuer's fraud hold on an unfamiliar recurring or international-looking charge, or a spending limit on the card itself that has nothing to do with DimeBox's own daily spend limit. Updating the card on file at /wallet resolves the overwhelming majority of these without needing to treat it as anything more unusual than a card declining anywhere else.