Errors and recovery

Branch on the coded reason, and retry only what the response says is safe to repeat.

What to do about each code

Branch on the code, never on the message. The status tells you the class of problem; the code tells you which of five things to do about it.

What a failure looks like

A plain refusal

Validation failures, authentication and most not-founds. There is nothing to branch on beyond the status, and the message is for your logs — never for a control-flow decision.

{
  "error": "amount must be a base-unit integer string"
}

A coded refusal

Everything in the tables below. code is stable and safe to branch on; reason carries the underlying detail, such as a raw revert string, and is not stable.

{
  "error": "The operation cannot execute",
  "code": "EXECUTION_SIMULATION_REVERTED",
  "reason": "ERC20: transfer amount exceeds balance"
}

400

Invalid request or missing setup

Correct malformed fields, an unsupported network or token, or grant the allowance the coded reason names.

401 / 403

Authentication or policy

Refresh the session JWT or verify project API-key scope.

404

Unknown or expired operation

A prepared operation that expired, or one never submitted, is gone. Prepare again.

409

Duplicate or in-flight operation

Reuse the existing operation id and keep polling; a coded in-flight conflict is retryable shortly.

422

Simulation rejected

Inspect the coded reason, adjust the calls or the amount, and prepare again.

429

Rate limited

Honor Retry-After and retry with bounded exponential backoff.

503

Measurement unavailable

Nothing is known to be wrong — the coded reason names what could not be read. Retry.

Change the input — a retry cannot succeed

The request was understood and refused for a reason that will not change on its own. Retrying the identical body returns the identical error.

Code	What it means
`SWAP_AMOUNT_TOO_SMALL`	A bridge or DEX on the route rejects the amount as below its minimum. Raise the amount or pick another corridor.
`EXECUTION_SIMULATION_REVERTED`	The calls revert deterministically. The response carries the raw revert reason; fix the call, not the retry policy.
`NO_ROUTE_AVAILABLE`	In exact-output mode, no offered route can GUARANTEE the requested amount reaches the recipient, so it is treated as unroutable rather than quoted with a shortfall.
`SWAP_QUOTE_MOVED`	Prepare fetched a fresh route and it is worse than the one the user reviewed. Re-quote and ask the user again — never sign past this.
`INSUFFICIENT_NATIVE_BALANCE`	On the self-funded rail: the balance does not cover the amount plus the gas ceiling. Lower the amount or fund the account.
`SELF_FUNDED_NOT_EXECUTABLE`	The transfer was simulated against the recipient and reverted.
`FEE_TOKEN_REQUIRED`	The executor rail always charges in an ERC-20, so a preview must name feeToken.
`EXECUTOR_RAIL_NATIVE_UNSUPPORTED`	The executor cannot carry the native coin — it has no allowance to pull against. A native operation belongs to the self-funded rail.
`EXECUTOR_RAIL_PREVIEW_UNSUPPORTED`	That rail prices ERC-20 transfers only; the call could not be read as one.

Do a one-time setup, then repeat the request

Nothing is wrong with the request. Something the account needs once — per token, for life — is not in place yet.

Code	What it means
`EXECUTOR_ALLOWANCE_MISSING`	The executor holds no allowance for this token. Ask POST /transaction/allowance-setup what it needs, relay that, then prepare again.
`EERC_ALLOWANCE_MISSING`	The same, for a private deposit: there the spender is the encrypted-token contract rather than the executor.
`EIP7702_UNSUPPORTED_NETWORK`	This network has no chain-level EIP-7702. Use the endpoint that answers with the rail the network does carry.

Retry the same request

A measurement could not be taken, or something of yours is still in flight. Nothing is known to be wrong, and the identical request can succeed shortly.

Code	What it means
`AUTHORIZATION_IN_FLIGHT`	A concurrent first-operation authorization is already in flight for this account. Once it establishes the delegation, later operations need none.
`SENDER_OPERATION_IN_FLIGHT`	A previous operation for this account has not settled yet.
`TRANSACTION_NOT_VISIBLE`	The node has no record of the reported hash yet.
`SELF_FUNDED_ESTIMATE_UNAVAILABLE`	The transfer could not be measured.
`NATIVE_BALANCE_UNAVAILABLE`	The account balance could not be read.
`SELF_FUNDED_NONCE_UNAVAILABLE`	The account's transaction count could not be read.
`SELF_FUNDED_CHAIN_UNAVAILABLE`	The chain could not be checked for whether these bytes already landed — the check fails closed rather than guessing.
`ENGINE_UNAVAILABLE`	The execution service could not be reached.

Re-sign — do not resend the same payload

The signed material no longer matches the chain. Resending it can never mine; the account has to sign again.

Code	What it means
`USER_OP_NONCE_STALE`	The account's nonce moved on. Prepare again and sign the new operation.
`SELF_FUNDED_NONCE_SPENT`	The nonce those bytes carry is already used.
`SELF_FUNDED_UNDERPRICED`	The signed fee is below what the network will accept. Re-sign the SAME nonce higher — a new nonce would leave two competing transactions.

Treat it as already done

A conflict that means the thing you asked for exists. These make a call safe to repeat after a lost response.

Code	What it means
`APPROVAL_ALREADY_GRANTED`	The allowance is already at least this size.
`TRANSACTION_ALREADY_REGISTERED`	Those exact bytes are already booked as an operation.
`SIGNED_TRANSACTION_ALREADY_MINED`	That transaction already landed.
`SIGNED_TRANSACTION_ALREADY_IN_FLIGHT`	The chain already knows the transaction.

Fix how you signed, not what you asked

Self-funded rail only. The request was fine; the serialized transaction the account produced cannot be carried.

Code	What it means
`SIGNED_TRANSACTION_UNSUPPORTED_TYPE`	Not an EIP-1559 transaction.
`SIGNED_TRANSACTION_WRONG_CHAIN`	Signed for a different chain id.
`SIGNED_TRANSACTION_NO_RECIPIENT`	The envelope names no recipient.
`SIGNED_TRANSACTION_VALUE_ZERO`	A native transfer of nothing.
`SIGNED_TRANSACTION_GAS_LIMIT_TOO_LOW`	The gas limit cannot cover the transaction.
`SIGNED_TRANSACTION_GAS_LIMIT_UNMINEABLE`	The gas limit is above what any block can include.
`SIGNED_TRANSACTION_MISMATCH`	The bytes do not describe the operation they were sent for.
`SELF_FUNDED_OPERATION_ID_REQUIRED`	The bytes call a contract, so they must name the swap that quoted them.
`SELF_FUNDED_RAIL_NOT_APPLICABLE`	This network's native transfers belong to another rail.

Documentation navigation

What to do about each code

What a failure looks like

A plain refusal

A coded refusal

Invalid request or missing setup

Authentication or policy

Unknown or expired operation

Duplicate or in-flight operation

Simulation rejected

Rate limited

Measurement unavailable

Change the input — a retry cannot succeed

Do a one-time setup, then repeat the request

Retry the same request

Re-sign — do not resend the same payload

Treat it as already done

Fix how you signed, not what you asked