/** * The px402 v2 §6.5 error taxonomy and its normative HTTP status mapping. * Mirrors `crates/px402-issuer/src/error.rs`, from the caller's side. * * # Why this is a hierarchy and not a string * * §6.5's eleven codes are not eleven equally-shaped failures: they partition * into five *dispositions*, and a wallet that gets the partition wrong fails * silently in a way that looks like flaky infrastructure. * * | Status | Disposition | What the wallet must do | * |---|---|---| * | 400 | reject | The request can never succeed unchanged. Do not retry. | * | 404 | not found | The object is not here. Do not retry. | * | 409 | **wait** | Conflict with existing state. **Retry once it clears.** | * | 410 | **recoup** | Permanently gone. **Reclaim the coin (§6.9); never retry.** | * | 500 | issuer fault | Retry with backoff. | * * The 409/410 pair is the one that matters operationally, and it is * symmetric: **a wallet that retries a 410 spins forever on a coin it should * be reclaiming, and one that recoups on a 409 abandons a coin that was only * temporarily locked.** Both are silent. Both look like the network. * * # The code outranks the status * * §6.5 fixes the mapping precisely because "wallets, facilitators and * relayers all branch on HTTP status before they parse a body". But a * *nonconforming* peer can still pair a code with the wrong status, and then * the two sources disagree. This module resolves the disagreement in favour * of the **code**, because that is the choice that is safe in both * directions: * * - `DENOM_REVOKED` arriving as a 409 — trusting the status retries forever; * trusting the code recoups, which is right. * - `KEYSET_NOT_COMMITTED` arriving as a 410 — trusting the status recoups a * live coin; trusting the code waits, which is right. * * The observed status is still kept ({@link PX402Error.httpStatus}) and the * disagreement is flagged ({@link PX402Error.statusDisagreesWithCode}) so an * operator can see a nonconforming peer rather than only its consequences. * When the code is absent or unrecognised there is nothing to outrank the * status with, and the status band decides. * * # Nothing here echoes a server body * * Messages are built from the code and the status only. A peer's `message` * field is free-form text that may quote a coin public key, a reserve * address, or a request the wallet would rather not see in a log line, and * error objects are exactly what gets logged. The code is the machine- * readable part and it is the only part kept. */ /** * The eleven §6.5 codes, verbatim. This list is the taxonomy: a code outside * it is not part of the contract and is treated as absent (see * {@link px402ErrorFrom}). */ export declare const PX402_ERROR_CODES: readonly ["KEYSET_UNKNOWN", "KEYSET_NOT_COMMITTED", "DENOM_REVOKED", "DENOM_EXPIRED", "BAD_DENOM_SIG", "BAD_PERMISSION_SIG", "TERMS_MISMATCH", "RESOURCE_MISMATCH", "INSUFFICIENT_VALUE", "MELT_RESERVED", "REPLAY_SETTLED"]; /** One of the eleven §6.5 codes. */ export type PX402ErrorCode = (typeof PX402_ERROR_CODES)[number]; /** * §6.5's normative status mapping, code by code. * * Note what is **not** here: no code maps to 500. §6.5 is explicit that * "Services MUST NOT return 500 for any condition in this table", because a * caller error surfacing as issuer fault is indistinguishable from a real * outage and gets retried against a request that can never succeed. */ export declare const CANONICAL_STATUS: Readonly>; /** Narrow an arbitrary value to one of the eleven §6.5 codes. */ export declare function isPX402ErrorCode(value: unknown): value is PX402ErrorCode; /** * Base class for every px402 protocol failure. * * The three flags are the whole point of the hierarchy, and they are set by * the subclass rather than by the caller: {@link retryable} (may the same * request be sent again once some condition clears?), {@link recoup} (is the * value permanently unreachable through this path, so the holder's route is * §6.9 reclaim?), and {@link idempotentSuccess} (did the request already take * effect, so that retrying accomplishes nothing?). */ export declare class PX402Error extends Error { /** The §6.5 code, when the peer sent a recognised one. */ readonly code: PX402ErrorCode | undefined; /** The HTTP status actually observed, when this came from a response. */ readonly httpStatus: number | undefined; /** The status §6.5 assigns to {@link code}; undefined when there is no code. */ readonly canonicalStatus: number | undefined; /** True when the peer paired a recognised code with a status §6.5 does not give it. */ readonly statusDisagreesWithCode: boolean; /** May this request be sent again once the stated condition clears? */ readonly retryable: boolean; /** Is the value permanently gone through this path, so the route is §6.9 recoup? */ readonly recoup: boolean; /** Did the request already take effect, making a retry pointless? */ readonly idempotentSuccess: boolean; protected constructor(name: string, message: string, flags: { retryable: boolean; recoup: boolean; idempotentSuccess: boolean; }, context: { code: PX402ErrorCode | undefined; httpStatus: number | undefined; }); } /** Common context every response-derived subclass takes. */ interface ResponseContext { readonly code: PX402ErrorCode | undefined; readonly httpStatus: number | undefined; } /** * **400** — `BAD_DENOM_SIG`, `BAD_PERMISSION_SIG`, `TERMS_MISMATCH`, * `RESOURCE_MISMATCH`, `INSUFFICIENT_VALUE`. * * The request is malformed or invalid. Retrying it unchanged will always * fail, so this is never retried automatically. The wallet's route is to fix * whatever it sent, which usually means the coin, the terms or the keyset it * used is not the one the peer expects. */ export declare class PX402RequestError extends PX402Error { constructor(context: ResponseContext); } /** **404** — `KEYSET_UNKNOWN`. The referenced object does not exist at this peer. */ export declare class PX402NotFoundError extends PX402Error { constructor(context: ResponseContext); } /** * **409** — `MELT_RESERVED`, `REPLAY_SETTLED`, `KEYSET_NOT_COMMITTED`. * * Conflict with existing state, **retryable once the stated condition * clears**: `KEYSET_NOT_COMMITTED` when the on-chain commitment confirms, * `MELT_RESERVED` only if that melt completes or was never validly * authorized. * * `REPLAY_SETTLED` is the exception within the exception: it is idempotent * *success*, not a conflict to wait out, so {@link retryable} is false for it * and {@link idempotentSuccess} is true. Retrying would only re-observe the * same completed effect. * * **A melt reserve does not lapse on a timer (§6.6).** `MELT_RESERVED` on a * spend does not become spendable again by waiting: once a coin's residual is * committed to a melt session, retrying the spend later yields * `INSUFFICIENT_VALUE`, not a restored balance. The retry here is for the * melt to be *completed*, not for it to expire. */ export declare class PX402ConflictError extends PX402Error { constructor(context: ResponseContext); } /** * **410** — `DENOM_REVOKED`, `DENOM_EXPIRED`. * * Permanently gone. **The response is recoup (§6.9), never retry.** This is * the error a wallet must not treat as transient: the denomination key is * withdrawn or its epoch is over, and no amount of waiting brings it back. * {@link retryable} is false and {@link recoup} is true, and the retry loop in * `client.ts` reads exactly those two flags. */ export declare class PX402GoneError extends PX402Error { constructor(context: ResponseContext); } /** * **500** — issuer fault. Retryable with backoff. * * §6.5 forbids returning 500 for any condition in its table, so a 500 is * never a caller error and a retry of the identical request is the correct * response. */ export declare class PX402ServerError extends PX402Error { constructor(context: ResponseContext); } /** * The request never produced a response: DNS, TCP, TLS, timeout, abort. * * Retryable, because nothing is known about whether the peer acted. Every * px402 write is idempotent under its own key (`commitmentHash` for withdraw, * `⟨C⁰_p, attempt⟩` for a melt session), which is what makes a blind retry * safe here. */ export declare class PX402TransportError extends PX402Error { constructor(detail: string); } /** * The chain's RPC endpoint will not serve a request the wallet needs to this * client: a public endpoint keeping some requests for clients with a key * (publicnode answers `eth_getTransactionReceipt`, and any state more than a * couple of hundred blocks old, with -32602 "Archive requests require a * personal token"). * * **Not retryable**, and not a protocol violation: the endpoint is the wrong * one for this wallet. Pass `rpcUrl`, or set `PX402_RPC_URL`, to your own. */ export declare class PX402RpcUnsupportedError extends PX402Error { /** The JSON-RPC method refused. */ readonly method: string; /** The endpoint's host (never its URL, which may carry a key). */ readonly rpcHost: string; constructor(method: string, rpcHost: string, detail: string); } /** * The peer answered, with something this SDK cannot act on: an unparseable * body, a signature count that does not match the request, a keyset whose id * is not the hash of its own contents. * * **Not retryable.** The same request produces the same malformed answer, and * unlike a 500 this is a disagreement about the protocol rather than a * transient fault. Retrying it hides a genuine interoperability bug behind a * backoff loop. */ export declare class PX402ProtocolError extends PX402Error { constructor(detail: string); } /** * There is no coin this wallet may spend for the requested amount (§7). * * `privacy: "strict"` **fails closed**: a freshly issued coin is not * spendable until at least one issuance window has passed (§9.1), and when * that leaves nothing spendable the SDK raises this rather than spending a * coin whose issuance and spend are separated by less than a window. That * gap is what links the two events, so "spend it anyway" is not a degraded * mode — it is the failure the mode exists to prevent. * * `privacy: "besteffort"` is the explicit opt-in to spending fresh coins. * There is never a silent fallback between the two. * * Carries only counts, never coin material. */ export declare class PX402NoCoinsError extends PX402Error { /** The amount that could not be covered, in base units. */ readonly requested: bigint; /** Total residual value the privacy mode allowed the selector to consider. */ readonly spendable: bigint; /** Coins held but withheld by the issuance-window hold; zero in `besteffort`. */ readonly heldForWindow: number; /** * Coins retired by §7's one-coin-one-merchant rule that still hold residual * value. * * Their value is real and on the registry's books; it is reachable only as * **fresh** coins, through §6.6 refresh. A non-zero count here means the * wallet is not out of money, it is out of *unpresented* money, and the * remedy is a melt rather than a withdrawal. */ readonly heldForRefresh: number; constructor(detail: { requested: bigint; spendable: bigint; heldForWindow: number; heldForRefresh?: number; privacy: string; }); } /** * The wallet holds the value, and cannot present it in one payment: every * cover of the amount needs more coins than one `X-PAYMENT` header carries. * * x402 sends the payment in a request header, and the server in front of a * merchant refuses one too large before the merchant's handler runs: nginx a * header line over 8 KiB (`400`) by default, Node a header section over * 16 KiB (`431`). So a payment carries at most {@link maxCoins} coins: what * the header budget ({@link maxHeaderBytes}, 7,680 bytes by default, nine * launch-ladder coins) holds, and never more than the facilitator's coin cap * (`MAX_COINS_PER_SPEND`, fifteen) -- a long resource URL takes room too. A * buffer of small change can hold enough and still need more coins than that. * * Raised **before any coin is selected**: nothing is retired and nothing is * sent. The remedy is larger coins -- `wallet.prewarm()`, whose next refill * plans for this price (the wallet records it) -- or, for `maxHeaderBytes` * alone, a larger budget if every merchant you pay accepts larger headers. * Not retryable unchanged. * * Carries only amounts and counts, never coin material. */ export declare class PX402HeaderBudgetError extends PX402Error { /** The amount that could not be presented, in base units. */ readonly requested: bigint; /** The header budget in bytes, when one was applied. */ readonly maxHeaderBytes: number | undefined; /** The most coins one payment could carry here (the coin cap, or fewer under the budget). */ readonly maxCoins: number; /** The fewest spendable coins that cover the amount (one of them split). */ readonly coinsNeeded: number; /** The header those coins would have made, in bytes, when a budget was applied. */ readonly headerBytesNeeded: number | undefined; /** What the {@link maxCoins} largest spendable coins add up to, in base units. */ readonly largestPayable: bigint; constructor(detail: { requested: bigint; maxHeaderBytes?: number; maxCoins: number; coinsNeeded: number; headerBytesNeeded?: number; largestPayable: bigint; }); } /** * Why a wallet declined to present coins through a facilitator (v3 §7). * * - `"unreachable"` — `GET /supported` failed or answered non-2xx. Retryable. * - `"malformed"` — it answered with something that is not a `/supported` * body this SDK can read, so the fee cannot be determined. * - `"unsupported"` — it settles no `batch-settlement`/`px402` kind for the * requirement's network. * - `"fee-missing"` — a v3-shaped body (a signer **list**) with no * `extra.feeBps`. The relayer set charges *something* and the facilitator * did not say what; guessing is exactly the overpayment this error exists * to prevent. * - `"fee-rule-unknown"` — it charges a fee and names no fee-rounding rule, * or one other than `"smallest-denomination"` (v3 §25.1). It would refuse * the rounded total this wallet presents, after the coins were retired. * - `"fee-over-max"` — the advertised fee exceeds the wallet's `maxFeeBps`: * the rate, or the fee on this price once rounded to the smallest * denomination beyond `ceil(price × maxFeeBps / 10 000) + smallest − 1`. */ export type FeeRefusal = "unreachable" | "malformed" | "unsupported" | "fee-missing" | "fee-rule-unknown" | "fee-over-max"; /** * The wallet will not present coins through this facilitator, because it * cannot establish — or will not accept — the relayer fee (v3 §7). * * Raised **before** any coin is selected, so nothing is retired under §7 and * no receipt is written: the 402 was never answered. An agent sees the * facilitator and the fee it was quoted rather than a silently larger * payment, which is the whole reason the fee is checked on the wallet side * at all — the facilitator recomputes the terms with the fee it charges, so * a wallet that guessed low would fail `INSUFFICIENT_VALUE` after retiring * its coins, and a wallet that guessed high would simply pay it. */ export declare class PX402FeeError extends PX402Error { /** The facilitator URL the merchant's requirements named. */ readonly facilitator: string; readonly refusal: FeeRefusal; /** The advertised fee in basis points, when one was read. */ readonly feeBps: number | undefined; /** The wallet's ceiling, when the refusal was `"fee-over-max"`. */ readonly maxFeeBps: number | undefined; /** * What the fee on the payment's price would have been, in base units -- * the rate's fee plus the rounding to the smallest denomination (v3 * §25.1) -- when the refusal was `"fee-over-max"` for a priced payment. */ readonly feeBaseUnits: bigint | undefined; /** * The most this wallet pays in fee on that price: * `ceil(price × maxFeeBps / 10 000) + smallest − 1` (zero at a ceiling of * zero), alongside {@link feeBaseUnits}. */ readonly maxFeeBaseUnits: bigint | undefined; constructor(detail: { facilitator: string; refusal: FeeRefusal; detail: string; feeBps?: number; maxFeeBps?: number; feeBaseUnits?: bigint; maxFeeBaseUnits?: bigint; }); } /** * The merchant's px402 terms name a payout tier this wallet will not pay * under (v3 §16's 2026-10-01 note). * * px402 pays the Instant tier (`extra.tier: 0`). A Batched (`1`) payment would * commit the payer's coins at the registry and then be handed to no relayer * and no batch, so the merchant would never be paid and would answer as if * nothing had been paid; px402 facilitators refuse it `TIER_UNSUPPORTED`. * The wallet refuses first, **before any coin is selected**: nothing is * retired and no receipt is written. A 402 whose px402 entry names no tier, * or names it as anything but the JSON number `0`, is refused the same way. * * Not retryable: the merchant has to quote `tier: 0`. */ export declare class PX402TierError extends PX402Error { /** `extra.tier` as the merchant served it (`undefined` when absent). */ readonly tier: unknown; constructor(tier: unknown); } /** * Why a payment through the exact-scheme bridge (v3 §26) did not reach the * merchant as a verified authorization. * * **Nothing committed** -- no receipt, no coin debited (the coins the * facilitator saw stay retired to this merchant, as §7 requires): * * - `"timeout-too-short"` -- the merchant's `maxTimeoutSeconds`, capped at * 3600, is under 120: a relayer could not sign an authorization that lives * long enough. Refused before anything is sent. * - `"refused"` -- the bridge facilitator's `/verify` said no, or its * `/settle` answered `4xx` (`BRIDGE_UNSUPPORTED`, `BRIDGE_TIMEOUT_TOO_SHORT`, * a §6.5 code), which it does only before committing. * - `"unreachable"` -- `/verify` did not answer, or answered `5xx`. `/verify` * writes nothing, so this one is retryable. * * **Committed** -- a `settled` receipt with `delivered: false`, the coins * debited, and a recourse the wallet pursues (`wallet.pursueBridgeRecourse()`): * * - `"no-relayer"` -- `502 BRIDGE_NO_RELAYER`: the coins are committed and no * relayer signed. The facilitator cancel-refunds them (§26.6). * - `"settle-unknown"` -- `/settle`'s answer was lost, or was a `5xx` other * than `BRIDGE_NO_RELAYER`. Assumed committed, as every unanswered settle * is (`fetch.ts`). * - `"malformed"` -- `/settle` succeeded and its `extra.bridge` is not an * authorization this wallet can read. * - `"to"`, `"value"`, `"valid-after"`, `"valid-before"`, `"nonce"`, * `"asset"`, `"from"`, `"signature"` -- the authorization failed that check * of §26.8 step 4 (and §26.12): it pays someone other than `payTo`, a value * other than the price, is not valid from 0, expires within 10 seconds, is * not under this payment's `payoutNonce`, names another token, comes from * an address no relayer on `/supported` pays from, or does not recover to * `from` under the token's EIP-712 domain. It is **not** delivered. */ export type BridgeRefusal = "timeout-too-short" | "refused" | "unreachable" | "no-relayer" | "settle-unknown" | "malformed" | "to" | "value" | "valid-after" | "valid-before" | "nonce" | "asset" | "from" | "signature"; /** * A payment through the exact-scheme bridge (v3 §26) that the wallet stopped * before the merchant, or that no relayer would sign. See {@link BridgeRefusal} * for every {@link reason}. * * {@link committed} is the question that matters. `false`: nothing moved and * nothing was recorded. `true`: the coins are committed at the registry, the * receipt chain holds the payment as settled and undelivered, and the wallet * keeps a recourse for it (v3 §26.8 step 7) -- **never pay again for it**: a * retry is a second payment. The coins come back through the facilitator's * cancel refund (§26.6), or through the wallet's own dispute when the * facilitator does not act. * * Carries codes and addresses the wallet itself chose to send, never a * server's prose. */ export declare class PX402BridgeError extends PX402Error { /** The bridge facilitator the payment went to. */ readonly facilitator: string; readonly reason: BridgeRefusal; /** Whether the payer's coins are, or may be, committed (see the class docs). */ readonly committed: boolean; /** The facilitator's error code (`error` / `invalidReason`), when it named one. */ readonly facilitatorCode: string | undefined; constructor(detail: { facilitator: string; reason: BridgeRefusal; detail: string; httpStatus?: number; facilitatorCode?: string; }); } /** * The issuer no longer holds the keys of an epoch this wallet holds coins * of, so it cannot refresh them (K1): it answers a melt of one `410 * EPOCH_RETIRED`. * * What it means for the coins, by kind: * * - **Whole coins** no merchant has seen ({@link wholeCoins}) are still * money: the registry and the facilitator verify them against the epoch's * committed keyset until its spend window closes ({@link spendableUntil}). * Spend them whole -- the wallet does not split them any more, since a * split leaves change only a melt could return. * - **Residual a payment left** ({@link strandedBaseUnits}) can come back * only through a melt, which this issuer refuses, or a recoup (§6.9) if the * operator announces one for the epoch. * * Raised by `IssuerClient.melt` from the issuer's answer, and reported by the * wallet with the counts filled in: in `wallet.refresh()`'s outcome * (`retired`), in `wallet.readiness().retiredEpochs`, and through * `onWarning`. Not retryable: the issuer will answer the same way. * * Carries only counts and amounts, never coin material. */ export declare class PX402EpochRetiredError extends PX402Error { /** `"EPOCH_RETIRED"`: the issuer's code (outside §6.5's eleven). */ readonly reason = "EPOCH_RETIRED"; /** The retired epoch, when the wallet knows which one. */ readonly epochId: bigint | undefined; /** Its keyset id, `0x`-prefixed. */ readonly keysetId: string | undefined; /** Whole, unpresented coins of the epoch: spendable whole until {@link spendableUntil}. */ readonly wholeCoins: number; /** Their value, in base units. */ readonly wholeValueBaseUnits: bigint; /** Coins carrying residual a payment left, which no melt will return. */ readonly strandedCoins: number; /** That residual, in base units. */ readonly strandedBaseUnits: bigint; /** Unix seconds: the epoch's spend window closes (§4). */ readonly spendableUntil: number | undefined; constructor(detail?: { httpStatus?: number; epochId?: bigint; keysetId?: string; wholeCoins?: number; wholeValueBaseUnits?: bigint; strandedCoins?: number; strandedBaseUnits?: bigint; spendableUntil?: number; }); } /** The issuer's code for a melt of a coin whose epoch it no longer holds (K1). */ export declare const EPOCH_RETIRED = "EPOCH_RETIRED"; /** * `px402.open` was asked to start a wallet from scratch on a seed that has * been used before. Restart it with `px402.recover`. * * `open` starts the withdraw counter at 0. On a seed that has withdrawn, the * next withdrawal would re-derive coins it already took -- keys that may * already be spent, under blinding factors already used (§6.13) -- so the * withdrawal buys coins worth nothing and the reuse can link them. The * evidence `open` checks is the reserve's on-chain withdraw nonce (nonzero * once the reserve has withdrawn) and a stored receipt chain passed in * `config.receipts` (the seed has paid). Either one refuses. * * `px402.recover` rebuilds the buffer and resumes the counter above every * coin it finds; with no `sources` it uses the SDK's public ones. */ export declare class PX402SeedUsedError extends PX402Error { /** The reserve's on-chain withdraw nonce, when that is what refused. */ readonly reserveNonce: bigint | undefined; /** How many stored receipts were passed in. */ readonly receipts: number; constructor(detail: { reserveNonce?: bigint; receipts: number; }); } /** * Build the right {@link PX402Error} subclass for a response. * * Classification is by **code first** (see the module docs for why that is * the safe direction), falling back to the status band when the body carries * no recognised code. An unclassifiable status yields a bare * {@link PX402Error} that is not retryable — the conservative choice, since * retrying something whose disposition is unknown is how a wallet spins. */ export declare function px402ErrorFrom(status: number, body: unknown): PX402Error; export {};