Paid and blocked: why your agent still gets a 402 after paying

1. The second 402: you paid in the wrong protocol version

Symptom. The payment verifies or settles, you retry with proof of payment attached, and the server returns 402 again as if you never paid.

Likely cause. A header version mismatch. x402 v1 servers expect the payment proof in an X-PAYMENT header; v2 servers expect PAYMENT-SIGNATURE. Send the wrong one and the server does not reject your payment. It simply never sees it, so it does the only thing it can do: issue a new 402. From the server's side, your retry is indistinguishable from a first request.

How to verify. Log the exact header your client sent on the retry, and decode the 402 response to see which protocol version the server's payment requirements declare. If the versions differ, you have found it. No amount of re-paying fixes a header the server is not reading.

The fix. Send the header the server's version expects, and pin the protocol version on both sides of the integration. This failure is silent and repeatable, which makes it the most common cause of a 402 after paying, and the cheapest to fix once identified.

2. Verification rejects a payment that looks right

Symptom. The server, or its facilitator, refuses the payment outright. No settlement, no resource, and an error that tells you less than you need.

Likely causes. x402 verification is exact, in the literal sense. The amount must match the requirement exactly; overpaying or underpaying by the smallest unit fails verification, so a client that rounds or adds a buffer is wrong in a way that looks like generosity. The EIP-712 domain's chain ID must match the network in the payment requirements, or the signature is invalid for that requirement no matter how correct everything else is. A malformed signature fails, and so does a wallet that does not hold enough of the token. And a payment can be refused on compliance screening even when the cryptography and the balance are both fine.

How to verify. Compare the amount in your payment payload against the requirement in base units, digit for digit. Check the chain ID in the signed domain against the network the 402 specified. Confirm the paying wallet's balance. If a facilitator verified the payment, read its actual response: a rejection carries a reason code, and the troubleshooting guide maps each one to its layer and its safe next step.

The fix. Match the requirement exactly: same amount in base units, same network, same asset. Treat "close enough" as a bug class in payment code, because the verifier does.

3. The facilitator said no, or said nothing

Symptom. Your payment never reaches the server's verifier at all, or comes back rejected from the intermediary.

Likely causes. Most x402 verification runs through a facilitator, and facilitators fail in their own ways: a rejection with a stated reason, facilitator downtime, or a deployment mismatch such as pointing a testnet facilitator at a mainnet requirement it does not support.

How to verify. Capture the facilitator's raw response, not just your client's summary of it, and look up its reason code in the error code lookup. Confirm the facilitator endpoint in your configuration actually serves the network named in the payment requirements.

The fix. Act on the stated reason; it tells you which of the failure modes above you are actually in. And log facilitator responses permanently. A rejection you did not record is a failure you will have to reproduce from memory. One related trap for sellers: failed payments never settle, so they never appear in settlement data. If you only watch settled payments, rejected attempts are invisible to you, while buyers experience those invisible failures as "I paid and nothing happened."

4. Payment settled, nothing delivered

Symptom. The payment is settled on-chain. The resource, the report, the data, the completed action, never arrives. There is no pending state to wait out.

Likely cause. An ordering bug on the seller's side, documented in seller postmortems: the server settles the payment before doing the work, the work then fails, and the buyer is left with a settled payment and no output. Because x402 has no escrow and no on-chain refund path, the buyer's only remedy in the standard flow is the seller issuing a manual refund.

How to verify. Assemble the evidence before you contact anyone: the payment requirements you were given, the payment payload you submitted, the settlement transaction, and the server's response to your paid request. You will notice the gap immediately. A transaction hash proves a payment happened. It does not prove who paid it, what it was for, or that you are the party entitled to the undelivered resource. Anyone can copy a hash out of a block explorer.

What fixes it. Honesty first: no client-side tool can force a seller to deliver or refund, and nothing retrofits an escrow into a settled payment. What you can do is arrive with evidence instead of an anecdote, and, where a seller supports redemption, prove you are the payer with a signature, not a screenshot of a hash. That distinction is the entire recovery game in x402.

The checklist

When an agent reports paid-and-blocked, work this order before re-paying anything:

1. Which header did the retry carry, X-PAYMENT or PAYMENT-SIGNATURE, and which version does the server require?
2. Does the amount match exactly, in base units, against the 402's requirement?
3. Does the EIP-712 domain chain ID match the network in the requirements?
4. What did the facilitator actually say? Is there a reason code on record?
5. Did it settle? If yes and nothing arrived, stop retrying: gather the requirements, the payload, the transaction, and the response. You are in the evidence-and-redemption case now, not the retry case.

Most paid-and-blocked incidents resolve at step 1 or 2. The rest are only solvable if you kept the evidence, so keep it from the first request, not after the first failure.

Where callx402 fits

callx402 is Payload's diagnostics tool for exactly this state. Its six tools (x402_status, x402_diagnose, x402_evidence, x402_explain, x402_recover, x402_resolve) are read-only by design: they never charge, execute, retry, or repay. They answer which failure this is, what the evidence shows, and what the recovery path is. The local package holds no keys, in any version, and has zero dependencies; hosted actions are available for agent workflows that would rather call than install. Where callx402 supports redemption, it requires EIP-191 wallet-signed payer authorization: you sign with the wallet that paid, and the signature, not a transaction hash, is the credential. A hash alone is rejected, deliberately, because a hash is public information and proves nothing about who is asking.

What callx402 does not do, stated plainly: it does not custody funds, execute trades, or move money on your behalf, and it cannot guarantee a recovery. If a seller settled and vanished, the protocol gives nobody a lever to reverse that. What it gives you is the diagnosis, the evidence assembled in one place, and a redemption path that verifies the right person is asking.

This guide is maintained here. It was first published on dev.to on October 13, 2026.