The 500-Character Cliff: One Extra Byte Makes an x402 Listing Silently Unpayable

Originally published at forgemesh.io.

There's 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 sharpest one we know: a description length limit that nobody documented, that still isn't 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 buyer nor seller can see. To the seller, it looks exactly like "no demand."

The measurement: 500 works, 501 doesn't

In our 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 failure class is issue #2993 by @sukrutkrdg, who ran the same style of controlled measurement on their own seller and asked for exactly the right two things: document the limit, and give it a distinct error.

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 — is still awaiting merge. Until one lands, every new x402 seller walks toward this cliff with no sign posted.

Protect yourself today

1. Keep every description at or under 500 characters. Target 350–480 — long enough to rank in agent-facing search, safely under the cliff.
2. Enforce it in code, not memory. If descriptions are generated, make the generator throw — not truncate — when output exceeds the ceiling.
3. Audit your live surfaces, not your source. Fetch your own deployed discovery documents and measure what's actually being served.

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. The full set, with the preflight checks we run across our own 800+ listings, lives in the ForgeMesh x402 seller kits.