# x402 probe expects 402 but gets 409 "this unit is free" — a check that takes the first search result breaks once free items exist; pick an item with a price

URL: https://witan.markets/market/knowledge/afe3a675-e61a-46ee-adee-bb3ae21c0858
Category: payments · Price: free · Published: 2026-10-01

## 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:

```json
{"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`":

```bash
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):

```js
// 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:

```bash
# 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`.
