Errors
Baton returns conventional HTTP status codes and a JSON error body. This page covers the errors you are most likely to meet and what to do about them.
Payment errors (402)
A payment that fails admission returns 402 with an x402 error body:
{"x402Version": 2, "error": "PAYMENT_REQUIRED", "errorReason": "<reason>"}errorReason | Meaning | Fix |
|---|---|---|
replay | The payment nonce was already used. | Sign a fresh authorization with a new nonce. |
authorization_expired | validBefore is in the past. | Re-sign with a later validBefore. |
authorization_not_yet_valid | validAfter is in the future. | Set validAfter to 0 or a past time. |
invalid_max_amount | The authorized amount does not match the price. | Quote the baton first; authorize the quoted amount. |
invalid_token | The asset isn’t an accepted payment token for the active network. | Pay in an accepted asset (USDC or EURC) — use the asset contract from the 402 challenge’s accepted[] for the active network. |
merchant_not_configured / settler_not_configured | A server-side payment configuration gap. | Transient — retry; if it persists, contact support. |
For developers on a prepaid balance, an insufficient balance is also a 402 — top up and retry.
Baton state errors (409)
A 409 Conflict means the baton’s state does not allow the operation:
BATON_WITNESSED— the baton has been document-witnessed and is locked for writes. A witnessed baton is read-only by design.CHAIN_FLAG_CONFLICTS_OVERWRITE— you sent an overwrite-style write to a hash-chained baton. A chain only grows; append instead.
Not found (404)
A 404 means the baton id or token does not exist, has been hard-deleted, or — for a token — has expired or been revoked. A baton inside its tombstone window is recoverable; one past it is gone.
Idempotency
If a billable call fails midway — a dropped connection, a timeout — retry it with the same Idempotency-Key: you get the original result and are not charged twice. Reusing a key with a different body is a 409 IDEMPOTENCY_CONFLICT. The full contract (scope, the 24-hour window, the lodestone interplay) is on the canonical Idempotency page.
Limits and warnings
When a baton is running low on a resource — egress, time, writes — Baton does not wait for it to fail. Successful responses carry inline warnings while there is still allowance left, so you can extend the baton before it expires. Treat a warning as a prompt to act, not an error.