TollNode

Why agents can't pay your x402 API: 5 silent failures

Five ways an x402 API turns paying agents away with no alert, and what a probe of our own paid routes found on 17 November 2026, including a bug we fixed.

By the TollNode teamPublished 7 min read

A toll plaza where three lanes are blocked by a height bar, a closed door and a lowered barrier, and delivery vans turn back, while the one open lane stands empty

Short answer

  • An x402 seller only sees the buyers who got through. A buyer whose client chokes on the 402, or who called the wrong HTTP method, leaves no payment and usually no log line.
  • The five common causes: a PAYMENT-REQUIRED header too big for Python's aiohttp (limit 8,190 bytes), a paid route that ignores POST, a price string the SDKs now reject, settling before the result is usable, and retries that pay twice.
  • On 17 November 2026 two of our own routes sent a 402 header over aiohttp's limit. We trimmed it; a probe the same night found every paid route answering an empty POST with a payable 402, the largest header at 7,518 bytes.
  • Each failure can be tested in under a minute with an unpaid request, which costs nothing.
On this page
  1. Why do these failures stay invisible?
  2. 1. The 402 header is too big for the buyer's client
  3. 2. The paid route answers the wrong HTTP method
  4. 3. The price string isn't in canonical form
  5. 4. You settle before you know the answer was usable
  6. 5. A retry signs a second payment
  7. Check your own x402 API in a minute

Python's aiohttp, a common HTTP client in agent code, refuses any response header line longer than 8,190 bytes. Until the evening of 17 November 2026, two of our own x402 routes broke that limit: the price header for our Google data tool was 9,320 bytes and the LinkedIn one 8,752. A Python agent built on aiohttp that asked either route for a price got an exception instead of an offer, and nothing on our side logged it. This post covers that bug and four others like it: failures that cost an x402 seller paying customers while every dashboard stays green. It is written for anyone selling an API over x402, and for agent builders trying to work out why a paid call never went through.

Why do these failures stay invisible?

A seller's numbers start at the first settled payment. Everything before that point happens on the buyer's machine: the client sends a request, reads the 402, decides whether it can pay, signs. If any step fails, the buyer gives up and the seller sees, at most, one unpaid request in the logs, which looks exactly like a curious visitor.

Your own tests rarely catch it either. curl and Python's requests accept much longer headers than aiohttp. A health check that carries an API key never sees the 402 at all. The only reliable test is to be the buyer: send the same unpaid request an agent would send, with the client an agent would use.

FailureWhat the buyer seesWhat the seller sees
402 header too largeA client exception, no offerOne unpaid request
Wrong HTTP method404 or 405One unpaid request
Price string not canonicalPayment rejected before signingOne unpaid request
Settling on a useless answerCharged for nothingA sale
Retry signs a new paymentCharged twiceTwo sales

The last two look like revenue, which is worse: they are the failures that turn into refund requests and bad reviews in directories that test sellers by paying them.

1. The 402 header is too big for the buyer's client

Two delivery trucks under one height-limit bar: one carrying a tall stack of boxes is stopped by the bar, the other with a single flat box drives through.
Same lane, same price. The bigger load never reaches the booth.

x402 version 2 puts the whole offer in one response header, PAYMENT-REQUIRED, as base64-encoded JSON. Base64 adds a third to the size of whatever goes in. aiohttp's ClientSession defaults max_field_size and max_line_size to 8,190 bytes, and an answer over that raises a ClientResponseError before the agent's code ever reads the price.

Our headers grew because of the discovery block that x402 directories read: an example of the tool's output and a schema of its fields. For a tool that returns rich data, the example alone ran to several kilobytes. Another seller, boscolabs, found the same thing on 29 of their 30 routes and published how their tests missed it.

What we changed on 17 November 2026: the 402 now carries the shape of the output (one item per list, short strings) instead of a full example. The full example stays on the tool's page and in our machine-readable docs, where size doesn't matter.

Our routesBefore the fixAfter the fix
Largest header line (name and value)9,338 bytes (Google data)7,518 bytes
Routes over aiohttp's 8,190-byte limit20

After the fix the median header line across our catalog is 3,574 bytes.

Keep a margin. A header at 8,100 bytes passes today and fails the day someone adds a field to the schema. We now treat 8,000 bytes as the ceiling and re-measure after every catalog change.

2. The paid route answers the wrong HTTP method

A toll booth with a bricked-up door that a parcel bounces off, and an open door beside it that a second parcel enters, with an arrow sign pointing to the open door.
If the buyer knocks on the wall, at least put up a sign.

The seller picks which method gets a price. The buyer's client picks which method it sends. When they differ, the buyer gets a 404 or 405 and never learns there was something to pay for.

On 14 November 2026 a developer sent an empty POST to 137 advertised x402 paid routes on 78 hosts. Only 42 answered with a payable 402. 49 said 404 and 45 said 405. (A commenter on the post said the raw probe data could not be downloaded, so treat the exact split as one person's measurement.) The pattern is easy to believe: most x402 tutorials price a GET, and most agent tool calls send a JSON body with POST.

Our own probe on 17 November sent the same empty POST to every paid route in our catalog: every one answered 402 with a full offer, in a median of 246 milliseconds from our test machine. A GET to the same routes gets a 405 with an Allow: POST header and a one-line pointer to the docs. That is a choice, and it has a cost: an agent that only knows how to GET cannot buy from us. We made it because our tools take structured input that doesn't fit in a URL.

If your input is small enough for a query string, price both methods. If it isn't, answer the wrong method with 405, an Allow header and a short JSON error, so at least the agent's logs say what happened.

3. The price string isn't in canonical form

x402 prices travel as strings of the token's smallest unit. USDC has 6 decimals, so one cent is "10000". In November 2026 the official TypeScript, Go and Python SDKs started rejecting any amount that is not plain digits. The test cases name what fails: "1e4", "10000.0", "0.01", "0x2710", "1_000", "+1000", and " 1000 " with spaces.

A seller who builds the amount with a float, a template string or a locale-aware formatter can produce one of those without noticing, and every buyer on a current SDK then refuses the offer before signing. Our probe found every route's amount was a plain integer string. The check is one line:

const canonical = /^[1-9][0-9]*$/.test(offer.amount); // atomic units, no decimals, no exponent

4. You settle before you know the answer was usable

This one shows up as revenue. The builder of vet402, a service that buys from x402 sellers and records what comes back, published a ledger of 14,991 settled paid calls counted up to 13 November 2026: 510 of them returned nothing usable, mostly a 5xx, no status at all, or a 202 Accepted. Their article points out why: the reference Express middleware cancels settlement only when the status is 400 or above, so a 202 or an empty 200 settles like a real answer.

Under the exact scheme there is no built-in refund. Once settled, the money moves back only if the seller sends a new transfer.

Our rule since launch is verify, run, then settle only on a healthy, non-empty result. A timeout, an upstream error or an empty answer ends with no settlement, so the buyer's signed authorization expires unused. After three failures in a row a tool is paused until we fix it, which keeps agents from paying into something broken. If your tool can't finish inside one request, don't sell it under exact with a 202. That needs a payment that settles when the work is done, such as a hold you capture later under the auth-capture scheme.

5. A retry signs a second payment

An agent's request times out. It retries, signs again, and the new authorization carries a new nonce, so it is a new purchase. If the first call did finish on the server, the buyer has now paid twice for one result. Nothing in the exact scheme links the two attempts.

The fix is the payment-identifier extension. The client adds an id to its payment; the server caches the answer under that id. A repeat with the same id and the same request within the cache window returns the cached answer and skips payment; the same id with a different request gets 409 Conflict. It only works when both sides support it, so a seller should declare it in the 402 and a buyer should send it.

We'll be plain about where we stand: we stop a single signed payment from being used twice (the nonce), and API-key callers can send an idempotency-key that returns the first result without a second charge. We don't yet support payment-identifier for x402 retries. It is on our list.

Check your own x402 API in a minute

The unpaid request is free, so this script costs nothing to run. It uses aiohttp on purpose, because that is the strictest common client:

# pip install aiohttp
import asyncio, base64, json, re
import aiohttp

ROUTES = ["https://api.example.com/paid/search"]  # your paid routes

async def check(session, url):
    try:
        async with session.post(url, json={}) as r:
            raw = r.headers.get("PAYMENT-REQUIRED", "")
            if r.status != 402 or not raw:
                return f"{url}: POST got {r.status}, no payable 402"
            size = len("PAYMENT-REQUIRED: ") + len(raw)
            offer = json.loads(base64.b64decode(raw))["accepts"][0]
            amount_ok = re.fullmatch(r"[1-9][0-9]*", offer["amount"]) is not None
            return (f"{url}: 402, header {size} bytes"
                    f"{' (over 8,000)' if size > 8000 else ''}, amount {offer['amount']}"
                    f"{'' if amount_ok else ' NOT canonical'}")
    except aiohttp.ClientResponseError as e:
        return f"{url}: aiohttp refused the answer: {e.message[:80]}"

async def main():
    async with aiohttp.ClientSession() as session:
        for line in await asyncio.gather(*(check(session, u) for u in ROUTES)):
            print(line)

asyncio.run(main())

If your server validates the body before it asks for payment, replace {} with a real example input. That covers failures 1 to 3. Failures 4 and 5 only show up when someone pays, so test them by buying from yourself once with a small wallet: make the tool fail on purpose and check that no settlement happens, then kill the connection mid-call and see what a retry costs.

To see what a healthy offer looks like, send the same request to any of our tools: curl -s -X POST https://tollnode.com/api/v1/nodes/web-search -H 'content-type: application/json' -d '{}' -i. What is x402? explains every field in it, and x402 MCP shows the same offer travelling over an MCP connection.


Questions people ask

How big can an x402 PAYMENT-REQUIRED header be?

x402 sets no limit, but buyers' HTTP clients do. Python's aiohttp refuses a response header line over 8,190 bytes, name included. Keep the whole header under 8,000 bytes and test with aiohttp, not curl.

Should a paid x402 route answer GET or POST?

Whichever your buyers send. Agent clients pick the method themselves, so a route that only prices GET turns away every POST. If your input needs a JSON body, answer GET with 405 and an Allow: POST header so the client can see what went wrong.

Does a 202 Accepted count as a delivered x402 call?

Not for a buyer who wanted the result in that response. A 202 means the work was only accepted. Settle a single-request call only after a 2xx that is not 202 and carries a non-empty body.

How do I stop an agent from paying twice when it retries?

Each exact-scheme payment carries its own nonce, so a fresh signature is a fresh purchase. The payment-identifier extension lets a server return the cached answer for a repeated payment id instead of charging again.

Can I test my x402 API without spending money?

Yes. The unpaid request is free: it should come back as a 402 with the offer. That one request shows whether the method, the header size and the price format work for a buyer.

Try it on TollNode

Live prices. Pay per call with x402 or an API key, charged only when the call returns a usable result.

Sources

  1. aiohttp client reference: ClientSession max_line_size and max_field_size, aiohttp
  2. Our x402 API was invisible to every aiohttp agent, and our own tests couldn't see it, dev.to
  3. I POSTed to 137 x402 paid routes. 49 of them returned 404., dev.to
  4. x402 returned 202 after payment? Data from 14,991 paid calls, dev.to (vet402)
  5. fix(evm): reject non-canonical exact amounts (#4303), x402 Foundation
  6. Payment-identifier extension, x402 docs

Written by the TollNode team. We run a pay-per-call catalog of AI models and live data for agents, so what we write about x402 and MCP comes from serving those calls. Facts are checked against the linked sources and our own live endpoints on the date shown. How we write.