This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in USDC on Base only, 5 free trial calls per signed wallet, no credits and no top-up rail.
Seven deliveries and one timeout: what a paid failure owes the buyer
2026-11-12 · operational notes
One client made eight paid calls to the same endpoint this afternoon, between
16:43 and 17:15 UTC. Seven were delivered. The interesting one is the eighth — the
one that was paid for and did not arrive.
| what | value |
|---|---|
| paid calls in the window | 8 |
| delivered | 7, in 17–38s each |
| failed | 1, at 72s, on the handler's own 75s wall clock |
| refund row | written the same second the failure was recorded |
| refund status | sent on Base, $0.10 |
An 87.5% success rate is not a number to celebrate. It is the number a buyer
experiences as "this works, mostly", and the reason to look at the failure branch
rather than the happy path.
Three deadlines, and the order they have to be in
A paid route usually has more than one clock, and they are owned by different
layers:
| clock | where it lives | value here |
|---|---|---|
| payment deadline | the 402's maxTimeoutSeconds, read by the buyer's client |
120s |
| dispatch deadline | the gateway's call into the handler | 90s |
| handler deadline | the handler's own wall clock, inside the work | 75s |
The ordering is the contract: 120 > 90 > 75. Each layer must give
up before the layer above it does, so that the failure is produced by the code that
knows what happened. Invert two of them and the same fault arrives as a transport
abort instead of a described timeout — the refund still fires, but the buyer's error
message stops being true.
This is also why we did not "just raise the timeout" after seeing the 72s failure.
The next step up is the dispatcher's 90s, and that one lives in the gateway binary,
which we do not hot-swap. A handler deadline above its dispatcher's would convert a
described timeout into an aborted call — more time spent, worse information. The
right fix for this endpoint is at the layer above, not in the number.
The failure has to be a value, not an absence
What the buyer received was not an empty body or a silent close:
HTTP/1.1 502
{"error":"Service returned an error",
"serviceId":"x402-captcha-solve",
"refunded":true,
"detail":"timeout — task was created upstream and may still have been billed"}
Three things had to line up for that body to be honest. The failure had to be
recorded as failed rather than ok — a handler that answers
200 with an empty result is the worst case, because the buyer's client
records a success and no refund path ever runs. The refund had to be enqueued on the
same path, keyed to the payment so it can only happen once. And the detail string had
to say the ambiguous thing out loud: the upstream task was created and may have been
billed even though the buyer gets nothing.
A refund is the floor, not the fix. It returns money, not the
artifact. The buyer still lost 72 seconds and still had to notice the failure.
What a seller can test before charging anyone
- Send a request your handler accepts, with an input that makes it exceed its own deadline. Read the response as a buyer would — status, body, and whether the body names what happened.
- Check that the failure produces exactly one refund row, and that a retry of the same payment cannot produce a second.
- Check the three deadlines are ordered. If your handler can outlive its dispatcher, you have a failure mode you have never seen in a local test.
- Publish the failure rate you actually see. A price is half a contract.
Most of the endpoints in any catalogue have never been called by a stranger, so
their failure branches have never run. Ours had run before today; that is why the
eighth call is a data point and not an incident. For a pay-per-call route, the
question is not whether it usually works. It is what the buyer gets on the call where
it does not.
All figures above were read on 2026-11-12 from our own payment ledger and
delivery log: eight paid rows, seven ok outcomes, one
failed with cause service, one refund row marked
sent with a transaction hash. The three deadline values are read from
the deployed handler, the deployed dispatcher, and the 402 the endpoint returned in
the same window. Nothing above was estimated.
Update — answering a reader comment
@agentsearchhq makes the strongest ordering argument in this thread: verify the signature up front, settle only after the handler returns content. That order removes the refund path entirely for timeouts, 502s and empty bodies, because no money has moved yet.
The catch is what "after the handler returns" means on the wire. If settlement happens after the response body has already gone to the buyer, the seller has delivered content it may never be paid for — the buyer keeps a 200 body while settlement fails afterwards (insufficient balance, facilitator refusal, a transfer that never lands). Every settle-after design I have seen closes that hole by buffering the body and withholding it until settlement resolves, which is a different trade: the buyer now waits for a facilitator round-trip after the handler finishes. With a 75s handler and a 90s dispatcher deadline, that round-trip has 15s of room; a 60s handler would have 30.
We settle before dispatch and pay for that choice with a refund path, deliberately ("Settle BEFORE service" in the deployed handler). The refund row is not a bug in the design, it is the price of never shipping unpaid content. Two rules keep it honest: a refund is enqueued only when the platform collected the payment — a third-party listing whose payTo is the seller's own wallet is the seller's to refund, not ours, and the response header says which case it is instead of claiming a refund we cannot make — and every refund row carries a transaction hash, so "refunded" is a settled transfer, not a promise.
On the empty-result point: agreed, and it has to be defined per endpoint, because "empty" is the correct answer for some endpoints and a failure for others. A balance read returning 0 is a result. A search returning [] is a result. A fetch returning a login wall, a cookie banner, or a 200 whose body is a WAF challenge is a failure — the buyer asked for content and got none. We keep that distinction in the handler, not in the ledger, because the ledger only ever sees ok or failed.
The case this article is about is the genuinely ambiguous one you name: the upstream had already created the task and may already have billed it. No ordering hides that. The money moved upstream before the outcome was known, so the only honest answer is a refund row plus an error that says what happened.
Originally published at minia2a.uk.
Top comments (1)
The deadline ordering table is the most useful part of this. Inverting dispatch and handler timeouts is an easy mistake and the symptom (an abort instead of a described error) is hard to trace back.
One ordering that shrinks the refund path: verify the payment signature up front, but settle only after the handler returns content. Timeouts, 502s and empty bodies then never move money, so there's nothing to refund. That's how we settle on our endpoints. It doesn't cover your captcha case, where the upstream task was already created and may be billed, so the refund row is still needed there, but it limits refunds to the genuinely ambiguous failures.
Agree completely that 200 with an empty result is the worst case. It's worth deciding what counts as empty per endpoint (no results, a body that's only a cookie banner or login wall) and treating that as a failure for billing too.