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.
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.