Errors and recovery

Mermail returns a stable code with every wallet failure. Fix the call from the code instead of retrying the same request, because a transfer is not idempotent.

Amount and argument errors

These are safe to fix and call again in the same turn. Nothing was sent to PayBox.

Code	What happened	Recovery
`paybox_amount_requires_decimal`	An integer `amount` was sent for an asset whose decimals Mermail knows	Resend with `amount_decimal` set to the amount the user asked for and omit `amount`
`paybox_amount_scale_mismatch`	`amount` and `amount_decimal` disagree	Resend with `amount_decimal` only
`paybox_amount_below_dust_floor`	Mermail has a trusted unit price and the transfer implies less than about $0.01	Ask the user for an amount worth at least $0.01, then retry with that `amount_decimal`. This code only appears when Mermail trusts the quote (DefiLlama or a proven portfolio price); an ambiguous portfolio balance fails open instead
`paybox_amount_value_mismatch`	The implied USD value differs from `value_cents` by more than 3x	Restate the amount, or correct `value_cents`
`paybox_invalid_arguments`	A required field such as `token`, `chain`, or `to` is missing or malformed	Read the asset from the portfolio and resend with the complete arguments

See catalog token transfers for the exact argument contract.

Approval errors

Code	Status	What happened	Recovery
`agent_approval_asset_missing`	`409`	The approval card was created before Mermail started recording the transfer asset	Ask the agent to start a new transfer so a fresh card is created
`agent_approval_persist_timeout`	`503`	Mermail could not record the approval in time	Do not submit again. Wait, then check the request status or start a new transfer
`confirmation_required`	`403`	A destructive non-PayBox Mermail tool was called without confirmation	Call `prepare_destructive_action` for the exact tool and arguments, then call the tool once; never use this recovery for PayBox
`confirmation_unavailable`	`503`	Confirmation storage is unavailable	Do not call the gated tool. Retry after the outage clears
`wallet_proposal_already_handled`	`409`	The proposal was already claimed, rejected, or changed	Call `get_agent_wallet` and stop. Do not retry submit. Create a new proposal only if status is `FAILED`
`wallet_proposal_not_pending`	`409`	The proposal is not `PENDING_REVIEW` (expired, submitting, or already finished)	Call `get_agent_wallet` and stop. Do not retry submit or create a duplicate
`wallet_paybox_credential_unavailable`	`409`	No active PayBox wallet credential matches this chain	Ask the user to connect or unlock the wallet on Agent Wallet. Do not retry submit or paste keys
`paybox_not_connected`	`409`	The mailbox has no usable PayBox connection	Paste `connect_handoff.console_url` (or open Agent Wallet → Connect). Do not reconnect the host MCP connector
`paybox_reauth_required`	`401`	PayBox delegation needs reauthorization	Paste `reauth_handoff.console_url` and wait for the user to reconnect PayBox inside Mermail
`OWNER_ACTION_REQUIRED`	tool status	A member cannot repair the workspace owner’s shared PayBox connection	Stop and ask the owner to connect/reauthorize PayBox in Mermail. No handoff is returned; do not construct one or switch identities
`paybox_write_retry_required`	`409`	A PayBox write raced with token refresh	Re-check `get_paybox_connection` / `get_agent_wallet`, then start a new write only if still connected
`paybox_oauth_unavailable`	`502` / `503`	PayBox OAuth / refresh could not complete	Stop. Ask the user to open Agent Wallet and reconnect if status is `REAUTH_REQUIRED`

confirmation_required applies to destructive non-PayBox Mermail tools. Do not call prepare_destructive_action for paybox_* or legacy Agent Wallet submit/reject tools.

Upstream PayBox errors

Code	Status	What happened	Recovery
`paybox_tool_error`	`502`	PayBox rejected the operation. Mermail forwards a sanitized reason, for example a nonce that is too low or a signing plan that has gone stale	Start a new `paybox_request_transfer`. Do not reuse the parked request or invocation id, and do not keep polling the old one
`paybox_upstream_uncertain`	`502`	The submission timed out or returned a malformed response, so its outcome is unknown	Never retry automatically. Verify the request status and the destination balance before any further action
`paybox_not_connected`	`403`	The mailbox has no active PayBox connection	Ask the user to connect PayBox on the Agent Wallet page
`paybox_signing_unsupported`	`422`	The authenticated MCP App continuation cannot safely use the returned signing plan	Stop. Do not expose the plan, retry the payment, or substitute a different signing route
`paybox_continuation_origin_not_found`	PayBox Submit failed	The widget tried a signing continuation (`submit_envelopes` or similar) without a matching audited origin (`pay_x402`, `request_transfer`, or `request_swap`). Paying with `paybox_use_service` produces this	Not success and not “awaiting signature.” Call `paybox_get_request` once if a `request_id` exists. Do not paste a signing URL unless that poll shows real `pending_signature`. If the origin is missing, wait for a fresh authorized `paybox_pay_x402` / transfer / swap. Do not call `reopen_signing_window`
`paybox_signing_app_unavailable`	signing session	After one catalog refresh, Mermail still has no usable PayBox signing UI resource for this invocation	Stop. Do not invent a signing URL or start a replacement payment automatically

pending, pending_paybox_approval, SUBMISSION_UNKNOWN, wallet_proposal_already_handled, and wallet_proposal_not_pending are not success. Treat them as unresolved. Do not retry submit or create another proposal unless status is FAILED.

Swap and x402 recovery

A pending swap is not success. Use its PayBox MCP App only if it shows a usable signing control, otherwise one returned signing handoff, then call paybox_get_request once only after the user confirms signing or asks for status. The model must not call reopen_signing_window.
Never replace a pending or uncertain x402 payment. Pay with paybox_pay_x402 only — paybox_use_service is unpaid mode: "probe" and is not a signing-continuation origin. The authenticated browser may finish signing in the PayBox window; the model must not call paybox_pay_x402 again to resume signing.
paybox_continuation_origin_not_found / Submit failed is not awaiting signature. Reconcile once, then wait for a fresh authorized paybox_pay_x402 if the origin is missing.
If an HTTP 402 challenge changes origin, resource/action, asset, chain, recipient, or exceeds the approved cap, stop for fresh authorization.
Charge required_charge = max(live quote, vendor prepaid floor) when a floor is resolved from same-origin docs or paybox_get_contract. Covering the live quote is not permission to skip the floor.
Treat x_payment as sensitive proof for the exact paid resource only. Never print, log, persist, or send it to another origin.
See swaps and x402 for the full workflow.

Portfolio reads during a PayBox outage

get_agent_wallet can report a connection.status of PAYBOX_UNAVAILABLE with an empty portfolio and a null portfolio_app. That means PayBox did not answer that one read, not that the delegated connection ended.

Read again later instead of telling the user to reconnect or re-authorize.
Do not present the balances from that response as final; they are missing, not zero.
The console keeps the last portfolio it loaded on screen while this happens, so what the user sees and what the tool returned can differ briefly.

A genuine disconnect shows NOT_CONNECTED, and an expired delegation shows REAUTH_REQUIRED. Those need the user: paste connect_handoff.console_url or reauth_handoff.console_url from get_paybox_connection / get_agent_wallet, or print mermail wallet connect-url / reauth-url. Never send the user to Claude, ChatGPT, or Codex connector settings for PayBox authorization.

Transfer amount rules

The argument contract these errors refer to.

​Amount and argument errors

​Approval errors

​Upstream PayBox errors

​Swap and x402 recovery

​Portfolio reads during a PayBox outage

Transfer amount rules

Amount and argument errors

Approval errors

Upstream PayBox errors

Swap and x402 recovery

Portfolio reads during a PayBox outage