Why x402 services fail verification
The practical causes behind unreachable endpoints, invalid requirements, stale schemas and paid-but-unusable responses.
DIRECT ANSWER
x402 services usually fail verification because the endpoint is unreachable, the advertised method or transport is wrong, payment requirements are incomplete or incompatible, the client cannot sign the requested scheme, settlement fails, or the paid response does not match the documentation. Discovery metadata can also be valid-looking while pointing to a demo, stale route or unsafe operation.
Key takeaways
- Separate transport, quote, settlement and output failures so the fix is obvious.
- Return explicit machine-readable errors instead of generic 500 responses.
- Re-run the published buyer instructions after every protocol or facilitator upgrade.
Failure layers
A verification pipeline should record the first layer that failed: DNS/TLS, HTTP transport, MCP handshake, tool discovery, 402 requirements, signer compatibility, verify/settle or output evaluation. Calling every problem 'down' hides whether the provider, buyer client or facilitator needs to change.
| Layer | Typical symptom |
|---|---|
| Transport | Timeout, TLS error or wrong method |
| Discovery | No tools, stale schema or invalid extension |
| Payment | Unsupported scheme, network or malformed requirement |
| Settlement | Verify passes but transfer or receipt fails |
| Output | 200 response is empty, wrong or unsafe |
Provider fixes
Expose a stable health endpoint separately from paid work, publish the exact protected route, keep examples valid and log correlation identifiers without leaking payment secrets. Test both insufficient-funds and valid-payment paths. Retire old discovery records when endpoints move.
Buyer-side diagnosis
Capture the unpaid requirement before changing client code. Confirm the client supports the advertised network and scheme, then compare the signed retry with official examples. Use a test network or narrowly funded wallet. If payment succeeds but output fails, stop retries to avoid paying repeatedly for the same broken operation.
Start with the first failed boundary
Troubleshooting becomes faster when each check stops at the first failed layer and records it precisely. If DNS does not resolve, changing payment fields cannot help. If the endpoint returns a valid 402, transport is no longer the leading problem. If settlement succeeds, the remaining failure belongs to tool execution or output delivery rather than the buyer's signer.
Preserve the exact method, sanitized URL, timestamp, status and correlation identifier. Do not reduce every case to "verification failed." A provider should be able to route the record to infrastructure, protocol, payments or product owners without reproducing the entire crawl first.
Transport failures: DNS, TLS, redirects and methods
Common transport failures include an expired certificate, a hostname that resolves only inside the provider's network, an IPv6 address with no working route, a redirect to a different or private host, and a protected path that accepts a different method than the registry advertises. A healthy marketing homepage does not disprove any of these route-level problems.
Test from an external dual-stack environment using the exact method and URL. Keep HEAD and GET behavior intentional, and do not redirect a paid API through login or documentation pages. If a route has moved, publish a clear redirect only when the method and payment contract remain safe; otherwise retire the old record and advertise the new one.
Requirement failures: a 402 that clients cannot use
A server can return HTTP 402 and still fail. The encoded requirement may be missing, malformed, mixed between protocol versions or bound to a different resource. Amounts can be non-positive or expressed in the wrong unit. The scheme, network or asset may be unsupported by the intended buyer, and an invalid timeout or destination can make signing unsafe.
Validate the emitted response with current client packages rather than a hand-built parser alone. Test every requirement option the server advertises. If one option is obsolete, remove it; clients may select differently, and an unusable alternative turns a healthy route into intermittent behavior across the ecosystem.
- Use current version-specific field names and header encoding.
- Bind the requirement to the exact protected resource.
- Express atomic amounts and asset identifiers consistently.
- Advertise only schemes and networks the server can settle.
Signer and settlement failures
Repeated 402 responses after retry often mean the server rejected the payment payload or never recognized the payment header. Check that the buyer registered the scheme and network the server offered, signed with the intended account and retried the same resource. On the server, inspect verification and settlement separately; a valid signature can still fail because of balance, allowance, timing, facilitator configuration or on-chain settlement.
Do not log private keys or reusable signatures while diagnosing. Record hashes, nonces, public addresses and facilitator correlation IDs sufficient to trace the attempt. Test on the corresponding non-production network before asking a buyer to repeat a failing mainnet payment.
Output failures after successful payment
The most expensive failure occurs when money moves but the promised work does not arrive. The tool may throw after settlement, return an empty success, produce the wrong media type or time out while an upstream dependency continues running. An automatic retry can create a second charge or duplicate a mutating action.
Design idempotency and charging semantics before launch. If work can fail after settlement, document refund or retry behavior and return a correlation ID. Validate the final response against the published schema, and track paid-but-unsuccessful calls as a first-class reliability metric rather than burying them inside HTTP 200 counts.
Discovery and documentation failures
A working route may still fail directory or Bazaar checks when metadata points to a demo URL, uses the wrong method, contains an example that does not validate or describes a tool that no longer exists. Copying a v1 discovery snippet into a v2 server can produce plausible-looking output that current facilitators reject.
Treat metadata as code. Review it in the same change as the route, run schema validation and make the published example part of an integration test. Remove retired entries instead of relying on registries to infer that they are obsolete.
A release checklist that catches most regressions
From a clean external environment, call the exact public route without payment and inspect the 402. Complete one testnet payment with the documented buyer setup. Validate the result, then exercise insufficient funds, unsupported network, invalid input, timeout and duplicate retry paths. Confirm that logs expose the layer that failed without exposing secrets.
After a package, facilitator or network upgrade, repeat the test rather than assuming compatibility from compilation. Finally, query the discovery surface and compare the listing with the deployed method, URL, schema and price. A short end-to-end check is cheaper than debugging buyers' repeated paid failures.
Related directory entries
Sources and methodology
TOLL·402 distinguishes public claims, registry discovery, unpaid quote checks and settled paid-call verification. Sources below support the visible claims; presence in a registry is not treated as verification.
- x402 FAQ — Official troubleshooting for repeated 402 responses.
- x402 client/server concepts — Responsibilities at each payment layer.
- TOLL·402 health report — Current large-scale health-label distribution.