> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mermail.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors and recovery
> Agent Wallet error codes for transfers, approvals, and portfolio reads, with the safe recovery for each.
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](/agent-wallet/catalog-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](/agent-wallet/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.
The argument contract these errors refer to.