Skip to main content
Every failure is the same shape:
error is a sentence written for a person to read. It is not a code to switch on — switch on the HTTP status. This is the one worth reading twice.
402 means this action needs payment. It never means an existing code stopped resolving. Every link you have created keeps working in every account state, including cancelled — see Permanence. The message always says so explicitly; if you show it to a user, show all of it.
402 appears in three distinct situations, told apart by the body:

​
Statuses

​
Retrying

429 and 502 are worth retrying with backoff. 502 from analytics means the recent half of the window is unavailable — we return the error rather than the older half alone, because a partial answer that looks complete is worse than a failure you can retry. Nothing else is worth retrying unchanged. A 409 on a payment means that credential is spent; get a fresh 402. A 400 on an x402 payment means the requirements moved; get a fresh 402 rather than adjusting the numbers yourself.

​
Creation is atomic

If creating a link returns an error, no link was created — quota checks bind inside the insert rather than being read beforehand, so concurrent creates cannot all slip past a limit. The same holds for machine payments: a settlement that fails releases its claim and leaves nothing behind, so you can retry with a working instrument.