Nine indexers are still sending an example we retired
2026-11-17 · measured from one day of gateway access logs At 17:09Z today we replaced the input example on a paid endpoint. The old example advertised seven parameter names and seven <PLACEHOLDER: …> values — the shape
2026-11-17 · measured from one day of gateway access logs
At 17:09Z today we replaced the input example on a paid endpoint. The old example advertised seven
parameter names and seven <PLACEHOLDER: …> values — the shape of a request, not one a
client can send. The new example carries real values that pass the handler's own validation.
Hours later, the access log still shows third-party probers sending the sentinels, byte for byte.
Not because they are broken. Because an example in a 402 is copied at ingest. Whoever
indexed us before the change holds a copy of the old one, and correcting our side does not recall theirs.
What the log actually shows
Counts below are from one day of our gateway log, with our own probe addresses removed. Each row is a
different way a caller arrives at a request that cannot work.
| Shape | Measured | What the caller needed |
|---|---|---|
| Sentinel copy-paste | 26 requests, 9 distinct probers | an example whose values pass validation |
| Dead id | 28 requests to a delisted service from 16 agents (2 are our own audit tool) | the replacement endpoint, machine-readable |
| Wrong namespace | 6 probers POSTing /api/abi, /api/tx/decode, /api/scrape
|
the real path, or a hint that survives parsing |
The sentinels were replayed by nine separate services — indexers, reliability probes, uptime monitors —
and two of those requests landed at 18:07 and 18:26, more than an hour after the new example shipped.
They are not testing us. They are replaying a stored example the only way a machine can: literally.
The dead-id row is our own gap, and it has two halves. A service we removed because it answered
"english" for every Latin-script language still gets asked for. Its 404 explains why and
names the replacement:
{"delisted":true,"error":"Service not found",
"id":"language-detect",
"hint":"language-detect delisted — it answered \"english\" for every
Latin-script language ... Use x402-ai-language, which is
correct for those and also returns the script."}
A different id, delisted as a duplicate listing, currently answers with the generic body instead:
{"error":"Service not found",
"hint":"GET /api/services for catalog",
"id":"ai-name-gen"}
That is the honest half of this post: the notice map exists and covers 25 ids; this one is not in it yet,
and 17 outside requests hit it in the same window. The fix is queued for the next binary, not shipped.
Why an example is a contract, not documentation
An HTTP doc page is written for a human who can read around a bad value. A 402's
extensions.bazaar.info.input is written for a client that will not read around anything:
it merges the object into a request and sends it. When those values are sentinels, the very first
thing an honest automated caller does is send a request that is guaranteed to be refused.
Two properties make this worse than a normal docs bug:
- It is cached outside your control. Directory snapshots freeze at ingest. You can see the lag in our log as a hard date: the placeholder-shaped requests do not stop when we deploy.
- It costs the wrong party. A probe gets a 400 for free. A buyer that pays first and is refused pays the gas for a refund. The refused request looks like a seller defect in every aggregator that scores delivery, while the actual defect is one string in an advertisement.
The rule we now use: an example that would be refused if sent is not an
example. Every advertised value must pass the handler's own validation on the day it ships, because the
copy that leaves your server is the copy that gets sent back.
The 404 body is an API surface
Our third row is different: callers arrived with the right capability name and the wrong prefix —
/api/abi instead of the paid path, from three unrelated crawlers. You cannot fix a guess.
You can make the answer parseable: keep id, keep a hint that names the catalog
route, and when an id was deliberately retired, say so with a field a client can branch on
("delisted": true) plus the replacement id. A 404 that only says "not found" burns the
caller's retry budget; a 404 that says "this id was retired, use that one" converts a dead link into
a sale.
What to check on your own endpoints
No special tooling: the 402 is the artifact, and the log is the judge.
# 1. does any advertised value still look like a sentinel?
curl -s https://your-host/x402/your-id | grep -o 'PLACEHOLDER[^"]*' | head
# 2. are retired ids answering with a replacement, or with nothing?
curl -s -o /dev/null -w '%{http_code}\n' https://your-host/x402/retired-id
# 3. who is replaying your old example? (adjust the log path)
grep 'PLACEHOLDER' /path/to/access.log | sed -E 's/.*ua=//' | sort | uniq -c | sort -rn
Line 3 is the one people skip. It tells you which directories froze your old advertisement, and
therefore which scores are being computed against a request shape you no longer publish. Re-indexing is
not instant and is not always possible; the only durable fix is to never ship a value you would refuse.
Originally published at minia2a.uk.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.