Avoiding interruptions
Paid x402 calls only fail for a few reasons, and all are easy to avoid:
| What happens | Why | How to avoid it |
|---|---|---|
Requests start returning 402 Payment Required again |
Your prepaid channel balance ran out, so the next voucher is no longer covered. | Keep USDC on Base in the payer wallet so the SDK can top up automatically (see Keep the channel funded). |
The first paid request returns 402 with deposit_below_minimum |
Your depositMultiplier sized the channel-opening deposit below the $2.00 minimum. The SDK default of 5 always does. |
Set depositMultiplier to at least ceil($2.00 / per-request price): 8334 for swap, 11112 for web3. The response repeats the required minimum in minDeposit. |
Requests return 401 Wallet not linked |
The wallet was unlinked from the application (or linked to a different one). | Do not unlink the wallet you are actively paying with. If you migrate, link it to the new application first: a wallet can be linked to only one application at a time. |
Requests return 401 Wallet not linked after deleting an application |
Wallet addresses are mapped per application. Deleting an application unlinks the wallet(s) mapped to it, so they can no longer pay. | Before or right after deleting an application, map the wallet to another application so x402 payments continue without discontinuation. |
Keep the channel funded
- Set
depositMultiplier, then let the SDK manage deposits. It sizes each deposit as multiplier × per-request price and re-deposits automatically when the balance runs low. The SDK default of 5 is far below the $2.00 minimum deposit, so use at leastceil($2.00 / per-request price)(8334 for swap, 11112 for web3) and raise it further for high call volumes to reduce the number of on-chain top-ups. See Sizing depositMultiplier. - Fund ahead of demand. Hold enough USDC on Base for your expected volume. You do not need ETH to deposit or pay (both are gasless for you). Keep a little ETH on Base only if you plan to use the on-chain self-withdraw fallback, which you broadcast yourself.
- Persist client channel state for long-lived clients (file storage, or Redis/Valkey for multi-instance) so a restart reuses the existing channel instead of opening a redundant one. Even without it, the SDK self-heals via corrective
402resync and on-chain state on the next paid request. - Watch your balance and top up before it reaches zero: see Monitoring your x402 usage.