An agent that wants to pay for an API call with x402 first makes the call without paying. The server answers 402 Payment Required and puts the offer (price, network, where to pay) in a PAYMENT-REQUIRED header, base64-encoded JSON. The agent reads it, signs a USDC payment, and sends the call again.
For a week, an agent built on Python's aiohttp never got to step two with our API. It didn't see a price. It saw an exception.
What happened
An outside checker for x402 endpoints, Pitcrew, scanned the sellers listed in the CDP Bazaar and e-mailed us: our PAYMENT-REQUIRED header was 11,664 bytes on one route, and aiohttp refuses any header line over 8,190 bytes:
aiohttp.client_exceptions.ClientResponseError: 400, message="Got more than 8190 bytes when reading: b'eyJ4NDAy...'"
We measured all 30 routes. 29 were over the limit, between 7.9 and 11.9 KB.
Why the header was that big
Most of it was discovery metadata, not the payment offer. To be listed in the Bazaar, each route carries an extensions.bazaar block: an example input, the input's JSON Schema, an example output and the output's schema. We had been generous:
- the output example was a full result row, 2 to 4.5 KB on some tools
- the output schema listed every field of a row with its type
- the input schema kept every description and every allowed value (one tool lists the same 36 metrics twice)
On top of that came signed offers (the offer-receipt extension, about 1.1 KB) that we added a week earlier. Base64 then adds a third.
We had a size budget: 12,000 bytes, chosen because Vercel and Node cap a header at 16 KB. The tests checked that budget for every route and passed. The budget was simply wrong: it was set by the most tolerant software in the path, not the strictest client.
Why we didn't notice
Every tool we used to check the API was tolerant:
- curl,
requests,httpxand urllib have no 8 KB line limit (or a much larger one) - our status probe always sends an API key, so it never sees a 402
- our x402 keepalive reads the 402 with urllib
So everything was green while one of the most common async HTTP clients in Python couldn't talk to us.
The fix
- The Bazaar output example is now the top level of the answer plus one short row (always with its
source_url); the output schema describes only the top level. Full field lists stay inGET /v1/tools. - If a route's input schema is still too large, descriptions get shorter first, then long enum lists go (also still in
GET /v1/tools). - The header budget is now 8,000 bytes. If signed offers would push it over, the second one is dropped; every route keeps both payment schemes.
Largest header now: about 7,860 bytes. Every route answers stock aiohttp with a readable 402.
The check we added
A daily job calls every route without a key, with aiohttp and httpx, decodes each PAYMENT-REQUIRED with the x402 library and fails if a header reaches 8,000 bytes. It runs from outside, like a stranger's agent would.
If you run an x402 API
- Measure your
PAYMENT-REQUIREDheader with a strict client, not curl. aiohttp's limit is 8,190 bytes for the whole line, header name included. - Proxies can be stricter still: nginx's default
proxy_buffer_sizefor response headers is one memory page, 4 or 8 KB. An agent behind such a proxy may fail even under 8 KB. - Keep discovery metadata small and point to a full schema elsewhere. The Bazaar needs enough to list you, not your whole API reference.
Thanks to Pitcrew for the report, with numbers that made it a same-morning fix.
Bosco Labs runs api.boscolabs.dev: company registers, sanctions lists and other official sources for AI agents, paid with an API key or per call with x402.
Top comments (0)