APIErrors and codes
Errors and codes
Every refusal code and HTTP error, with what to do.
Look up any refusal code or HTTP error and what to do about it. Refusals are HTTP 409 with one of 17 codes; other errors use { error, detail }.
Refusal codes
Member-level codes appear in members[i].denied with top-level denied: "member_denied". Batch-level codes appear in the top-level denied, with every member not_evaluated.
| Code | Level | Trigger | Extra fields | Retry and action |
|---|---|---|---|---|
per_tx_cap | Member | One purchase above perTxCap | bound, used, attempted | Never at this amount. Drop or split the purchase |
hourly_outflow | Member | Rolling 1 h total exceeded. Custom mandates only | bound, used, attempted, retryAfterSec, windowResetsAt | At windowResetsAt |
daily_outflow | Member | Rolling 24 h total exceeded | bound, used, attempted, retryAfterSec, windowResetsAt | At windowResetsAt |
monthly_outflow | Member | Rolling 30-day total exceeded. Custom mandates only | bound, used, attempted, retryAfterSec, windowResetsAt | At windowResetsAt |
per_seller_cap | Member | 24 h total to this counterparty exceeded | bound, used, attempted, retryAfterSec, scope | At reset, or pay another seller |
velocity_burst | Member | More than burstPerMinute purchases in 60 s | bound, used, attempted, retryAfterSec | After retryAfterSec |
per_agent_cap | Member | 24 h total for this agentIdentifier (Cardano) or agent address (EVM) | bound, used, attempted, retryAfterSec, windowResetsAt, scope | At windowResetsAt |
envelope_exhausted | Member | Lifetime envelope spent | bound, used, attempted | Never. Register a new wallet with a larger envelope |
registry_gate | Member | Cardano: agentIdentifier is not a live Masumi registry NFT, the registry is unreachable, or the Fixed price is unreadable. x402: no signed offer and unsigned sellers refused | reasonEnglish | Never. The seller registers or signs an offer. If the registry was unreachable, retry later |
price_above_published | Member | Above the registry Fixed price plus tolerance, or above the seller's signed x402 offer | bound, used, attempted | Never at this amount. Pay at most the published price |
counterparty_blocked | Member | On sellerDenyList, or not on a non-empty sellerAllowList | reasonEnglish | Never. The lists change only with a new wallet |
asset_not_listed | Batch | An asset the mandate does not govern (EVM: intent.asset is not one of the Safe's governed assets), an asset disabled on the network (asset_disabled), or more than 6 ADA on a token output | reasonEnglish, detail | Never. Fix the body |
body_mismatch | Batch, alarm (member on x402 seller binding) | The body disagrees with the intents or is malformed. EVM: the typed data disagrees with intent, uses a method the route refuses, reuses a nonce, or a SafeTx is not at the Safe's current nonce | reasonEnglish, detail | Never. Investigate the builder |
payee_unpinned | Batch, alarm (member on x402 seller binding) | An output pays an address other than escrow, an agent key or the wallet; x402 seller not bound | reasonEnglish | Never. Investigate |
utxo_unknown | Batch | Wallet not registered to this node, stale walletUtxoRef (stale_ref), or a Hydra head or snapshot problem | reasonEnglish, detail | Rebuild on the current UTxO, or register the wallet |
clock_skew | Batch, alarm | Validity interval missing, unbounded, wider than 7,200 slots, or not open now | reasonEnglish | Never. Investigate, then rebuild with a current window of 2 h at most |
reservation_conflict | Batch | Another batch's hold is open on this wallet | reasonEnglish | As soon as the hold clears (at most 120 s) |
Alarm codes set alarm: true and page Exchain's on-call engineer.
Common details
detail | Code | Meaning |
|---|---|---|
stale_ref | utxo_unknown | walletUtxoRef is not the wallet's current UTxO |
asset_disabled | asset_not_listed | Exchain disabled this asset on the network |
lovelace_rider | asset_not_listed | A token output carries more than 6 ADA |
unclaimed_outflow | body_mismatch | Fee or unclaimed ADA above 10 ADA, or outflow not claimed by an intent |
quorum_incomplete | body_mismatch | required_signers misses a quorum key |
agent_unsigned | body_mismatch | required_signers misses the agent |
not_open | clock_skew | The validity window is not open on Exchain's clock |
too_wide | clock_skew | The validity window is wider than 7,200 slots |
nonce_reused | body_mismatch | EVM: a different authorization reuses this nonce |
method | body_mismatch | EVM: Permit2 on POST /v1/evm/cosign, a SafeTx on POST /v1/x402/cosign or for a token with EIP-3009, or a SafeTx from a shadow wallet |
safe_nonce | body_mismatch | EVM: the SafeTx nonce is not the Safe's current nonce |
payee, amount, window, domain, token, … | body_mismatch | EVM: the typed-data field that disagrees with intent or the rules |
snapshot_stale | utxo_unknown | Hydra: snapshot number below the highest accepted |
hydra_head_untrusted | utxo_unknown | Hydra: the head is not trusted for this wallet or node |
HTTP errors
| Status | error | Routes | Meaning |
|---|---|---|---|
400 | bad_request | All | Schema, JSON or parameter failure. detail names the field |
400 | idempotency_key_mismatch | Co-sign, EVM co-sign, x402 co-sign | Header differs from batchId |
400 | batch_id_mismatch | EVM co-sign, x402 co-sign | batchId differs from the authorization nonce (for a SafeTx, the Safe nonce) |
400 | clock_rejected | Co-sign, EVM co-sign, x402 co-sign | Exchain's clock check failed. Contact Exchain |
400 | network_mismatch | Wallets, x402 wallets | Wrong network or chain |
400 | node_mismatch | Wallets, x402 wallets | nodeId differs from the token's node |
400 | asset_not_allowed, duplicate_asset, asset_mismatch | Wallets, x402 wallets | Asset checks |
400 | chain_mismatch | x402 wallets | The governed assets are on different chains; a Safe lives on one chain |
400 | invalid_constitution, unknown_invariant | Wallets, x402 wallets | The mandate does not compile |
400 | quorum_mismatch | Wallets, x402 | Quorum keys or threshold |
400 | owner_signature_required, safe_mismatch, not_deployed | x402 wallets | Safe consent or setup |
400, 409 | fee_mismatch | x402 fees | 400: Permit2, or the authorization does not move exactly what is due. 409: reused nonce (nonce_reused) or a SafeTx not at the Safe's current nonce (safe_nonce) |
401 | unauthorized | All | Missing or invalid token |
401 | agent_signature_invalid | EVM co-sign, x402 co-sign, x402 fees | Agent signature does not recover |
402 | fee_due | EVM co-sign, x402 co-sign | Settle fees first: Fees |
403 | owner_unbound | x402 wallets | Bind the owner in the console |
404 | not_found | All | Unknown route, or not your wallet or decision |
409 | wallet_exists | Wallets, x402 wallets | Different body for an existing wallet |
409 | idempotency_conflict | EVM co-sign, x402 co-sign | Same nonce, different content |
409 | fee_not_due, fee_unpayable | x402 fees | Nothing due, or the fee cannot be paid |
409 | A refusal code | x402 fees | The enclaves refused to co-sign the fee settlement; detail says why |
413 | payload_too_large | All, evidence | Body over 64 KiB, or bundle over 50 MB |
429 | rate_limited | Rate-limited routes (Limits) | With retryAfterSec and Retry-After |
500 | internal | All | Server error |
502 | rpc_failed | x402 wallets, EVM co-sign, x402 co-sign, x402 fees, bound | The chain could not be read. Nothing was decided; retry |
502 | deploy_failed, fee_settlement_failed | x402 wallets, x402 fees | Sending the Safe deployment or the fee settlement failed |
503 | quorum_unavailable | Co-sign, EVM co-sign, x402 co-sign, x402 fees | Quorum below threshold, with reachable, threshold, retryAfterSec (x402 fees: a bare error). detail: "stopped": signing paused (on EVM routes without retryAfterSec). detail: "record" (POST /v1/cosign only): audit record not written. Nothing consumed |
503 | unavailable | Every other POST | detail: "record": the audit record could not be written, so nothing was done. Retry-After: 5 |
503 | x402_unavailable, chain_unavailable | x402 wallets, x402 fees, bound | No RPC for the chain, or the chain cannot be read |
503 | busy | Any | Connection cap reached. Bare {"error":"busy"}, no envelope |
Retry rules for POST /v1/cosign: Refusals and retries.