When a paid request behaves unexpectedly, work through these checks in order. Most issues fall into one of four buckets.Documentation Index
Fetch the complete documentation index at: https://docs.myproceeds.xyz/llms.txt
Use this file to discover all available pages before exploring further.
I get a 402 but never the resource
The challenge is being returned, but the retry isn’t producing a 200. Check:
- The client retried with a valid payment payload (signature, network, and amount must match the challenge).
- The transaction shows
Completedin Transactions. - The events stream shows
Paymentfollowed byFulfillmentin Events.
Payment event but no Fulfillment, the upstream call is failing — see the next section.
Payment succeeded but the upstream call failed
The events stream showsPayment but not Fulfillment, and the transaction is Failed. Check, in order:
- Paywall Target URL is correct and reachable from Proceeds.
- Paywall custom headers and query parameters are valid.
- Service auth method matches what your upstream expects — see Forward upstream auth.
Error event for the underlying reason.
The wrong route is being charged
Requests are matching the wrong paywall, or your origin is being called with the wrong path. Check:- The paywall slug matches the URL the client called.
- The paywall Target URL points at the correct upstream path.
- The generated URL pattern:
/api/x402/pay/{serviceId}/{slug}.
MPP is not available
The Tempo / MPP path isn’t returning a working URL. Check:- Tempo is included in the paywall’s supported networks.
- The paywall exposes an MPP endpoint at
/api/mpp/pay/{serviceId}/{slug}. - The client is using an MPP-aware flow such as
mppx.
Still stuck?
Production checklist
Confirm settings before moving a service to mainnet.
Concepts
Refresh on services, paywalls, transactions, and events.