Field notes · 2026-08-04

The 500-character cliff: one extra byte makes an x402 listing silently unpayable

There is a class of bug in the agent economy that produces no stack trace, no 4xx, no alert — nothing. Your endpoint works. Your listing looks fine. And purchases simply never arrive. This is the story of the sharpest one we know: a description length limit that nobody documented, that still is not fixed upstream, and that we watched kill real purchases at exactly one character past 500.

The symptom: everything works except revenue

An x402 resource declares itself to discovery catalogs with metadata — including a free-text description. Write a description over a certain length and the resource doesn’t get rejected. It doesn’t error. It becomes silently unpayable: dropped or broken in the catalog pipeline in a way neither the buyer nor the seller can see. To the seller, it looks exactly like "no demand." We know how that feels from the inside — we once spent a weekend convinced our whole fleet was broken over a quietness that had a different cause entirely (that story here).

The measurement: 500 works, 501 doesn’t

In our own testing, purchases against an affected route succeeded with the description at 500 characters and stopped the moment it crossed to 501. No behavior change anywhere else — same route, same price, same challenge. One byte of prose was the difference between a purchasable resource and a ghost.

Credit where it’s due: the public report that nailed this class of failure is issue #2993 by @sukrutkrdg, who ran the same style of controlled measurement on their own seller (402.com.tr) and asked for exactly the right two things: document the limit, and give it a distinct error. That is how infrastructure gets better — a seller who measures instead of shrugs.

Upstream status: still not fixed

As of publication: the issue is open. A code fix attempt (PR #2995) was closed without merging. A documentation fix — PR #2998 by @Echolonius, which would at least write the limits down and name the rejection — is still awaiting merge. Until one of those lands, every new x402 seller walks toward this cliff with no sign posted.

Protect yourself today

The seller-side defense is simple, and we’re giving this one away in full:

• Keep every description at or under 500 characters. Target 350–480 — long enough to rank in agent-facing search, safely under the cliff.
• Enforce it in code, not memory. If your descriptions are generated, make the generator throw — not truncate, not warn — when output exceeds the ceiling. A hard failure at build time beats a silent one in the catalog.
• Audit your live surfaces, not your source. Fetch your own deployed discovery documents and measure what’s actually being served — length bugs love to hide in the gap between repo and production.

The uncomfortable part: this is one of at least four failure modes we know of that delist or break an x402 resource with zero error output — length is just the only one with a number this clean. The full set, with the preflight checks and submission flows we run across our own 800+ listings, lives in the ForgeMesh x402 seller kits — updated within a day of each discovery, because that is apparently the speed this ecosystem changes at.

Related reading: the v1/v2 client split that silently breaks settlements and field lessons from 500+ paid endpoints.