SpendPreflightdocs
Seller fixes / developer guide

Validate an x402 402 challenge

Check the version, resource and exact payment terms in your unpaid challenge.

Operator-maintained documentation
Live features and staging previews are distinguished. Index coverage is not yet available.

Preventive check, not a third observed failure

The November 2, 2026 capture recorded 0 invalid 402 challenges and 177 valid challenges among 186 fresh completed observations. Only HTTP 410 and timeout had nonzero failure counts. This guide is preventive; the aggregate did not measure separate missing-price, wrong-asset or bad-schema frequencies.

1. Read the correct protocol version

Use a parser that supports your advertised x402 version. Check the actual HTTP 402 status and the version-specific challenge representation: v2 uses PAYMENT-REQUIRED; v1 uses the response body. Inspect the decoded structure with the matching SDK schema. HTML from a proxy or a generic error page is not a valid payment requirement.

2. Check exact terms

Ensure the accepts list contains supported payment options with the intended scheme, network, asset, atomic amount and payTo. Confirm the asset contract belongs to that exact network and that the amount uses its decimals. Match the requested resource and method. Do not substitute a display price for atomic terms, copy a testnet asset into a mainnet requirement or treat a familiar address as proof of ownership.

3. Validate discovery separately

For advertised discovery metadata, make sure the documented method and example inputs reach the intended unpaid challenge. Keep valid free results and validation errors free. A schema-valid challenge does not prove registry binding, facilitator acceptance, catalog indexing, settlement or delivery. Run free Lint and use the Action for supported GET routes; review POST routes with the matching SDK and your own offline fixtures.

References