The seven most common x402 seller mistakes, and how to fix them
An x402 API asks for payment with an HTTP 402 Payment Required answer, and an AI agent pays it per call in stablecoins. That only works when the 402 is exactly what the agent's client expects. x402 Doctor calls every paid endpoint it can find once a day, about 50,000 of them, the way a paying agent would. On 17 October, 93% were payable as listed. These are the mistakes behind most of the rest,…
The seven most common x402 seller mistakes detailed in this report revolve around issues with payment processing on the x402 API. These mistakes include resource mismatch (2,009 endpoints), listed URLs that don't answer 402 (1,042 endpoints), offering only a testnet (206 endpoints), and improper configuration of the payment middleware.
The first issue, resource mismatch, occurs when the resource.url in the 402 response is different from the URL the agent called. This could be due to a relative path, another host, or an incorrect protocol (http:// instead of https://). To fix this, clients and indexes should check the resource and refuse the challenge if it doesn't match the called URL.
The second issue involves listed URLs that don't answer 402, which can happen due to various reasons such as using the wrong HTTP method, API-key checks, or misconfigured payment middleware. To resolve this, the payment middleware should be registered before the handler and before any API-key check, and the method used by the route should be accurately listed.
Lastly, 4% of payable endpoints only offer a testnet option, which is problematic for agents with real USDC on the mainnet. To address this, testnet and mainnet options should be offered side by side.
Brief written by urgent.news from Dev.to's own syndicated text. Machine-written — may contain errors; check the original before relying on it.
