A verification can be blocked when your wallet can’t cover the operation, or when your balance is frozen. Each maps to a distinct HTTP status with a distinct fix. Verifications that fail mid-flight on insufficient funds park instead of failing terminally, so you can resume them once you’ve fixed the cause.
Wallet gating, the 402 and 403 responses, and parked verifications all apply to live mode only. Test-mode verifications are free and never touch a wallet, so they never park on funds.
Why a verification can be blocked
Section titled “Why a verification can be blocked”Access is balance-first: a verification runs whenever your wallet has a positive spendable balance to cover the check. Two gates enforce this:
- Ingress gate: runs when you start a verification. Checks that the wallet is spendable and has funds.
- Execution gate: runs inside the verification workflow, immediately before each check runs. Dollars are debited before each check runs, so an insufficient balance fails the step without any check cost or arrears.
The two gates share one decision helper, so they cannot drift — the same input produces the same answer at both layers.
payment_required (insufficient funds or frozen wallet)
Section titled “payment_required (insufficient funds or frozen wallet)”Returned as 402 payment_required. Your wallet doesn’t have enough dollars for the operation, or the wallet itself is in the locked or closed state — for example, frozen by a card dispute (see Clawbacks and disputes). Top up to add funds; if the wallet is locked, contact support.
subscription_required (balance frozen after cancellation)
Section titled “subscription_required (balance frozen after cancellation)”Returned as 403 subscription_required. Your wallet holds a balance, but it is frozen because your subscription was canceled (or went past_due past the dunning grace). The funds are preserved, not forfeited — they become spendable the moment you re-subscribe. See Subscription.
Parked verifications resume after you fix the cause
Section titled “Parked verifications resume after you fix the cause”A verification whose execution gate trips on insufficient funds does not fail terminally. The verification parks in a non-terminal payment_required state. No check was ever run, so there’s no cost and no arrears. An audit event is recorded.
After a top-up, an auto-recharge, the next subscription cycle, or a re-subscribe that unfreezes the wallet, the parked verification resumes:
- Completed steps are not re-run — checks that already passed stay passed.
- The pending step retries through the same idempotent debit, so you are not double-charged even if the retry fires more than once.
How to fix payment_required
Section titled “How to fix payment_required”Top up your wallet: either a manual top-up or by ensuring auto-recharge is configured. If the wallet itself is locked or closed, contact support. A locked wallet (for example after a card dispute) must be released by our staff after review.
How to fix subscription_required
Section titled “How to fix subscription_required”Open Billing → Subscription and re-subscribe. Your frozen balance unblocks the moment the subscription becomes active.
Clawbacks and disputes
Section titled “Clawbacks and disputes”If a card payment is disputed (chargeback), the wallet is frozen while the dispute is open. If you win the dispute, the wallet unfreezes; if you lose it, the disputed funds are clawed back from your balance (floored at $0 — your balance never goes negative) and the wallet may stay locked for review. See Transactions for the dispute_clawback and dispute_reinstate_credit rows.
No double-charging on resume
Section titled “No double-charging on resume”A parked verification that resumes does not re-charge the steps it already paid for. You will see exactly one consumption row in Transactions per verification step, never two.
Audit trail
Section titled “Audit trail”Both denials emit audit events into the Activity log along with the wallet grant, consumption, dispute, and subscription lifecycle events. The audit trail is the system of record for SOC 2 reconciliation.
See also: Why is my account in payment_required?, Glossary.