Why Your x402 Call Keeps Returning 402

Why an x402 call keeps returning 402

The first 402 is the protocol working, not a failure. x402 is a two-request exchange: the server answers 402 with a signed offer, the client pays, then repeats the request carrying proof. If the second request also returns 402, the cause is almost always the client: wrong protocol version, wrong network, wrong asset, or a payload that expired.

Written for AI agents. The calls and filter values on this page are the literal interface our customers use, because our customers are software. If you are a person evaluating The Bot Wire, you are in the right place too: start with the docs, or connect an MCP client in one line and query browse every wire and its price at /mcp. Nothing here needs an API key or a signup.

Start by working out which of the two requests you are looking at, because the same status code means different things at each step.

The first 402 is the offer, not the error

HTTP reserved this code and never defined it. RFC 9110 says, in full, that the 402 status code is reserved for future use. x402 is one answer to what that use should be: the server replies 402 and attaches a machine-readable offer stating what it wants paid, in what asset, on what chain, and by when.

So a client that stops at the first 402 and logs an error has not hit a problem. It has received step one of two and given up. The background is in what x402 is and how an AI agent pays for an API call.

Read the offer before changing anything

The offer arrives base64-encoded in the PAYMENT-REQUIRED response header. Decode it first. Every field below comes from a live call to a $0.005 route on this service, and each one is a place a mismatch can hide.

Field	Live value	What a mismatch causes
`x402Version`	`2`	A v1 client signs the wrong envelope
`scheme`	`exact`	An unsupported scheme is never attempted
`network`	`eip155:8453`	Paying on a testnet settles nothing
`asset`	`0x8335...2913`	Wrong token, no settlement
`amount`	`5000`	Read as dollars, underpays by 1,000,000x
`maxTimeoutSeconds`	`300`	A payload signed 6 minutes ago is stale

Two of those deserve spelling out. network is eip155:8453, which is Base mainnet. Base Sepolia is 84532, and a wallet funded only on the testnet will sign a valid authorization that the facilitator correctly refuses to settle.

amount is 5000 in the token's own base units. USDC carries six decimals, so 5000 base units is $0.005. A client that treats the integer as dollars, or as wei with eighteen decimals, produces a number the server will not accept.

Why the error body will not tell you which one it is

The response body is identical whether the retry header is missing, malformed, or signed for the wrong chain. A live test sending a deliberately invalid header returned the same JSON as sending no header at all.

That is not much help when you are debugging, so treat the body as documentation rather than as a diagnostic. It always names the header the server wants and the network it settles on, which is enough to check your client against. The signal you actually want is on the client side: log the decoded offer, log the payload you signed, and compare them field by field.

Worth ruling out early: there is no free tier to fall back to. The preview routes were retired, so every wire in the catalogue is paid, and a 402 on a route you remember being free is expected. Free discovery now lives at /mcp and in the routing table, neither of which returns items.

The retry loop, one call at a time

For AI agents: copy this call

# free, no payment: browse every wire, its filters and its price
claude mcp add --transport http botwire https://thebotwire.com/mcp

# 1. the offer arrives as a 402 with a PAYMENT-REQUIRED header
curl -i "https://thebotwire.com/lang/releases?since=21d&limit=5"

# 2. decode the offer before signing anything
curl -sD - -o /dev/null "https://thebotwire.com/lang/releases?since=21d&limit=5" \
  | grep -i '^payment-required:' | cut -d' ' -f2 | base64 -d

# 3. an x402 v2 client signs and retries in one step
npx botwire-mcp   # or @x402/fetch in your own runtime

# the paid call settles at $0.005 in USDC on Base, no API key, no signup

Doing step 3 by hand is possible and rarely worth it. The signing, the retry and the 300 second validity window are what a client library exists to handle. What the wallet itself needs is covered in what an agent wallet needs to pay for data on Base.

FAQ

Is a 402 ever a real error rather than an offer?

Yes, when it repeats after a settled payment. If the facilitator has taken the funds and the route still answers 402, the payload settled against something other than this offer, most often a stale one signed outside the 300 second window. Sign fresh per request rather than caching an authorization.

Do I use the PAYMENT header or X-PAYMENT?

This service advertises x402 v2 and its own error body tells clients to retry with PAYMENT set. X-PAYMENT was the earlier spelling. If you are on a client written against v1, that version gap is the first thing to check, and it is why the table above lists x402Version first.

Can I test the flow without spending anything?

You can test discovery without spending anything. The MCP endpoint lists every wire, its filters and its price and returns no items, so an integration can be built and routed before a wallet is funded. The paid call is the only part that costs, and at $0.005 a single live call is a cheaper test than a testnet setup.

How do I stop an agent retrying a 402 forever?

Cap it. A 402 after a settled payment will not fix itself on the next attempt, so retry once and then surface the decoded offer alongside the payload you signed. An uncapped loop against a paid route is also how a small budget disappears, which is the case for setting a hard per-run spend limit.

Sources

The status code itself is defined by the IETF: RFC 9110 section 15.5.3 states that the 402 Payment Required status code is reserved for future use, which is why protocols such as x402 are free to define its semantics. The field values in the table were read from a live PAYMENT-REQUIRED header on this service on 8 August 2026. Current pricing and settlement configuration are published at thebotwire.com/health.