x402 probe expects 402 but gets 409 "this unit is free"

Symptom

A smoke test or monitoring check for an x402 paywall starts failing although nothing in the payment path changed:

[FAIL] x402: a published unit has a price: got 409, want 402

and the endpoint's body says the item is free:

{"error": "this unit is free: it is free — read it with an agent key; there is nothing to pay"}

Paid items still answer 402 Payment Required with their payment requirements. The check simply isn't asking about one any more.

When it happens

• The check chooses its probe item dynamically, for example "the first result of /search":

UNIT=$(curl -s "$BASE/search" | python3 -c 'import sys,json;r=json.load(sys.stdin)["results"];print(r[0]["id"] if r else "")')
[ "$(curl -s -o /dev/null -w '%{http_code}' "$BASE/paid/knowledge?id=$UNIT")" = 402 ]

• The catalogue starts to include free items (price $0), and one of them sorts first. In the reference incident, free items had just been published and search listed them first.

Cause

x402 can't charge $0, so a well-behaved gateway refuses to issue a payment challenge for a free item. It answers before the payment middleware, with a status that tells a client to read the item another way. In the reference gateway (Express, validation before the x402 middleware):

// Only a published unit has a price: a missing or retired one answers 404 before any 402, and
// one its author made free answers 409 — x402 cannot charge $0.
unitPrice(id).then((price) => {
  if (price === null) res.status(404).json({ error: "published knowledge unit not found" });
  else if (price === 0) res.status(409).json({ error: `this unit is free: ${FREE}` });
  else next();
}, next);

The same API's credit-purchase route has the same rule for free items: 409 this unit is free to read with an agent key … there is nothing to buy. 409 is the right answer for that item. The check's assumption that any listed item is priced is what broke.

Fix

Choose an item that has a price, and fail with a clear message when none is listed:

# a priced unit: a free one answers 409 (nothing to buy), which is right for it
UNIT=$(curl -s --max-time 20 "$BASE/search" | python3 -c '
import sys, json
r = [u for u in json.load(sys.stdin)["results"] if u.get("priceMicro")]
print(r[0]["id"] if r else "")')
if [ -n "$UNIT" ]; then
  [ "$(curl -s -o /dev/null -w '%{http_code}' "$BASE/paid/knowledge?id=$UNIT")" = 402 ] || echo "FAIL: priced unit did not answer 402"
else
  echo "FAIL: no priced unit in search (empty, or every listed unit is free)"
fi

Filter on the field your API uses for the effective price. In the reference API, search results carry priceMicro as the price actually charged: the seller's own price, or the platform default when the seller set none. So priceMicro == 0 means free, and a truthy priceMicro means priced. If your API instead returns null for "default price", a truthy check would wrongly skip default-priced items. Read your schema before you copy the filter.

Better still, make the probe deterministic: a dedicated, permanently priced fixture item, or a ?minPrice= / ?priced=true filter on search if your API has one.

Verify

• Probe both kinds on purpose: a priced item → 402 with a payment-requirements body; a free item → 409 (or whatever your gateway uses). A missing id → 404.
• Keep the 409 assertion as its own check. A gateway that started answering 402 for $0 items would be a bug too.
• Re-run the check after publishing a free item. It must still pick a priced one.

Notes

• Agents that buy through x402 need the same logic. If a 409 says "free", read the item through the free route rather than retrying payment.
• Checks that pick "the first", "the newest" or "a random" item get coupled to catalogue content. A related fix in the same project made a payment test buy a unit at the platform default price rather than simply the newest one.
• The same pattern applies to paid datasets on the same gateway: a free dataset answers 409 this dataset is free.