Recovery playbook
Reversal failures, decoded
Reversal errors are terse strings that arrive at the worst possible moment — mid-recovery, in front of a queue. Nearly all of them decode to one of three situations: you asked for too much, the money is gone, or you asked twice. Knowing which determines whether the fix is arithmetic, patience, or process. Here is the decoder, followed by the five-line pre-flight checklist that makes most of them impossible.
Error 1 — amount exceeds the transfer
You computed from the disputed or charged amount instead of the transfer, or ignored prior reversals. The rejection arrives instantly and nothing moved — fix the formula (round((refunded ÷ amount) × transfer.amount), capped at transfer.amount − amount_reversed) and re-run. This is the most common error and the most completely preventable.
Errors 2 and 3 — the money is gone, or you asked twice
Restricted or closed accounts reject outright; healthy-but-paid-out accounts accept and go negative, which is success wearing a disappointing costume — see the post-payout playbook for what follows. Already-reversed means your retry executed without a key: adopt the double-guard pattern (live-state check, intent-scoped key, persisted response) before the next storm.
Error 4 — account deauthorized
account.application.deauthorized fired: the seller disconnected your platform, closing the API path entirely. Freeze automated actions on that account, preserve existing findings as evidence, and switch to the reconnect-and-negotiate track. Some of those conversations succeed; none succeed faster for having a messy trail.
The pre-flight checklist
Fetch live transfer → sum existing reversals → clamp requested amount to the remainder → verify account status is active → attach the intent-scoped idempotency key. Five checks, one extra API call, and the entire family of reversal errors shrinks to the genuinely interesting cases. FeeGuard runs this checklist inside every automated action; failures surface as first-class states carrying Stripe’s verbatim error, so the queue shows what happened instead of hiding it.
Common questions
Can we reverse against a restricted account?
Usually no — resolve the restriction first or the call rejects. Restricted-until-debt-cleared is common after prior reversals, which is worth knowing before you create another one.
Is a negative-balance reversal "successful"?
API-wise yes, economically it is a claim on future volume. Plan communication and accounting around the claim, not the 200.