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 identifies the recovery action.

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

On submit, an expired preparation needs a new prepare and signature. On status polling, an operation that has not been submitted can return 404; verify its id and submission outcome first.

409

Duplicate or in-flight operation

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

422

Security or execution check failed

Inspect the security verdict or error code. Correct the reported cause, such as insufficient balance or a reverting call, before preparing again.

429

Rate limited

Honor Retry-After and retry with bounded exponential backoff.

503

Measurement unavailable

Inspect the code and retry guidance, then use bounded backoff for a temporary service or chain-read failure.

Change the input — a retry cannot succeed

Review the input or obtain a fresh quote before retrying. Repeatedly sending the same payload does not address the reported cause.

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_PREPARE_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.

Complete the required setup, then prepare again

The account needs a supported execution path or sufficient token allowance. Check the current state before preparing again; prior setup does not guarantee that an allowance is still sufficient.

Code	What it means
`EXECUTOR_ALLOWANCE_MISSING`	The executor has insufficient 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. Wait for it to settle, then follow authorizationRequired from the next prepare response.
`SENDER_OPERATION_IN_FLIGHT`	A previous operation for this account has not settled yet.
`SELF_FUNDED_ESTIMATE_UNAVAILABLE`	The transfer could not be measured.
`SELF_FUNDED_CHAIN_UNAVAILABLE`	The chain could not be checked for whether these bytes already landed — the check fails closed rather than guessing.

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

Security or execution check failed

Rate limited

Measurement unavailable

Change the input — a retry cannot succeed

Complete the required setup, then prepare again

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