Handling Execution Errors

Interpret fill and refund failure reasons returned after a request has been submitted

Once a request is submitted, execution can still fail during the fill or, if a fill isn’t possible, during the refund. These failures are surfaced as failReason (fill) and refundFailReason (refund) on the request object, distinct from the quote errors returned before a request is ever submitted. This guide outlines the possible fill and refund failure reasons and what each one means.

Fill Errors

failReason explains why a fill did not complete after a request was submitted.

Deposit & Validation Errors

Error Code	Description
DEPOSIT_CHAIN_MISMATCH	For strict deposit addresses, the deposit landed on a different chain than the one the address was registered for.
INCORRECT_DEPOSIT_CURRENCY	For strict deposit addresses, the token received doesn’t match the currency quoted for this request.
DOUBLE_SPEND	A second deposit was detected at an address whose first deposit was already processed.
DEPOSITED_AMOUNT_TOO_LOW_TO_FILL	The amount deposited is less than the quoted amount needed to complete the swap.
ORIGIN_CURRENCY_MISMATCH	The currency detected on origin doesn’t match the origin currency specified in the request.
TTL_EXPIRED	The request’s time-to-live window passed before it could be filled.
DEPOSIT_CONFIRMATION_TIMEOUT	The deposit transaction wasn’t confirmed within the expected window, so the request timed out and was routed to a refund.
DEPOSIT_REORGED	The deposit transaction was removed from the canonical chain by a block reorganization, so the request was failed.
ORPHANED_DEPOSIT_REFUND	A deposit at a deposit address couldn’t be matched to a fillable request, so the funds were refunded to the depositor.
BLOCKED_WALLET	An address associated with the request was flagged by wallet screening at fill time, so the fill was blocked. Funds are not automatically refunded and are subject to compliance review.

Solver Capacity & Balance Errors

Error Code	Description
SOLVER_CAPACITY_EXCEEDED	The solver’s available capacity for this route has been exceeded.
SOLVER_BALANCE_TOO_LOW	The solver doesn’t have enough native tokens or balance to construct the fill transaction.
SPONSOR_BALANCE_TOO_LOW	The sponsor covering transaction fees doesn’t have sufficient balance.
INSUFFICIENT_FUNDS_FOR_RENT	The user’s balance isn’t enough to cover rent/storage fees (Solana).
NEGATIVE_NEW_AMOUNT_AFTER_FEES	After deducting fees, the resulting amount is zero or negative.
AMOUNT_TOO_LOW_TO_REFUND	The amount to refund is zero or negative, or below the chain’s minimum transfer threshold, so no refund could be issued.
GASLESS_PERMIT_BALANCE_TOO_LOW	The balance available from a gasless permit wasn’t enough to complete the request, so the funds were refunded.

Swap Routing & Pricing Errors

Error Code	Description
NO_QUOTES	No liquidity providers returned a valid quote for this swap at fill time.
NO_INTERNAL_SWAP_ROUTES_FOUND	No internal DEX route was found between the specified currencies on this chain.
SWAP_IMPACT_TOO_HIGH	The swap’s price impact at fill time exceeds the acceptable threshold.
INSUFFICIENT_POOL_LIQUIDITY	The DEX pool doesn’t have enough reserves to complete the swap at any price.
SLIPPAGE	The swap couldn’t complete within the given slippage tolerance.
TOO_LITTLE_RECEIVED	The onchain swap executed, but the output amount was below the guaranteed minimum.
GENERATE_SWAP_FAILED	Generating the swap transaction (routing, calldata) failed before execution.
REVERSE_SWAP_FAILED	The reversal swap used to return funds to the user for a refund failed to execute or quote.

Transaction Construction & Gas Errors

Error Code	Description
TRANSACTION_TOO_LARGE	The serialized transaction exceeds the maximum payload size for the origin chain or RPC.
SWAP_USES_TOO_MUCH_GAS	The swap transaction would consume more gas than a single block allows.
NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE	A refreshed permit increased the rent/storage fee beyond the acceptable limit (Solana).
INVALID_GAS_PRICE	The submitted gas price is outside acceptable bounds.
QUOTED_GAS_LIMIT_EXCEEDED	The gas limit required at fill time was significantly higher than the gas limit quoted, so the fill was aborted.
JUPITER_INVALID_TOKEN_ACCOUNT	The token account required for the swap doesn’t exist or is invalid (Solana/Jupiter).

Onchain Execution & Revert Errors

Error Code	Description
EXECUTION_REVERTED	The swap contract call reverted during execution.
TRANSACTION_REVERTED	The transaction reverted at the blockchain level.
MISSING_REVERT_DATA	The transaction reverted, but the reason couldn’t be decoded from the returned data.
CONTRACT_PAUSED	The target contract is currently paused and not accepting calls.
TOKEN_NOT_TRANSFERABLE	The token enforces a non-transferable restriction (for example, a soulbound token).
TRANSFER_FAILED	A token transfer reverted at the contract level.
TRANSFER_FROM_FAILED	Transferring tokens from the user to the contract failed (for example, insufficient allowance).
TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE	The approved allowance is less than the amount being transferred.
TRANSFER_AMOUNT_EXCEEDS_BALANCE	The sender’s token balance is less than the amount being transferred.
INSUFFICIENT_NATIVE_TOKENS_SUPPLIED	The native token value supplied with the transaction is less than required.
INCORRECT_PAYMENT	The value or amount sent doesn’t match what the swap requires.
ZERO_SELL_AMOUNT	The swap was attempted with a zero input amount.
INVALID_SENDER	The address executing the swap isn’t authorized to do so.
INVALID_SIGNER	The signer on the order doesn’t match the address expected by the contract.
DESTINATION_TOKEN_TRANSFER_REJECTED	A token transfer reverted during the destination-side swap — typically the token itself rejecting the transfer (transfer tax, max wallet/transaction limits, or a blacklist).

Order & Signature Errors

Error Code	Description
ORDER_EXPIRED	The order’s expiration timestamp passed before it could be executed.
ORDER_IS_CANCELLED	The order was cancelled onchain before it could be filled.
ORDER_ALREADY_FILLED	The order was already fully executed and can’t be filled again.
SIGNATURE_EXPIRED	The signature used for token approval expired before execution.
INVALID_SIGNATURE	The provided signature is invalid or doesn’t match the expected signer.
INVALID_NONCE	The nonce provided has already been used or isn’t valid for this signer.
SEAPORT_INEXACT_FRACTION	The Seaport order specifies a fractional amount that can’t be fulfilled exactly.
SEAPORT_INVALID_FULFILLER	The caller isn’t an authorized fulfiller for this Seaport order.
PROTOCOL_DEADLINE_EXPIRED	The protocol order’s deadline expired before the fill could complete, so a no-fill-or-refund was submitted onchain.

Account Abstraction Errors

Error Code	Description
ACCOUNT_ABSTRACTION_INVALID_NONCE	The nonce in the account abstraction user operation is invalid or stale.
ACCOUNT_ABSTRACTION_SIGNATURE_ERROR	The account abstraction user operation’s signature is invalid.
ACCOUNT_ABSTRACTION_GAS_LIMIT	The gas required for account abstraction verification exceeds the allowed limit.

NFT Minting Errors

Error Code	Description
MINT_NOT_ACTIVE	The NFT mint phase isn’t currently active.
ERC_1155_TOO_MANY_REQUESTED	The quantity requested exceeds the contract’s allowed batch size.
MINT_QUANTITY_EXCEEDS_MAX_PER_WALLET	The wallet has already minted the maximum quantity allowed.
MINT_QUANTITY_EXCEEDS_MAX_SUPPLY	The requested quantity would exceed the collection’s maximum supply.

Other

Error Code	Description
FLUID_DEX_ERROR	The Fluid DEX protocol returned an error during the swap.
MANUAL_ADMIN_REFUND	The request was manually refunded by the Relay team via an admin action.
UNKNOWN	The fill failed for a reason that didn’t match a known error pattern.
N/A	The fill completed without failure.

Refund Errors

refundFailReason explains why a refund could not be completed after a fill failed. This field defaults to N/A when no refund failure has occurred.

Error Code	Description
AMOUNT_TOO_LOW_TO_REFUND	The amount to refund is zero or negative, or below the chain’s minimum transfer threshold, so no refund could be issued.
NEGATIVE_NEW_AMOUNT_AFTER_FEES	After deducting fees, the resulting amount is zero or negative.
SWAP_CURRENCY_NOT_ON_ORIGIN	The swap’s output currency isn’t available to bridge back to the origin chain, so the refund can’t be issued in the original currency.
REFUND_RECIPIENT_IS_VASP	The refund recipient was identified as a Virtual Asset Service Provider (VASP), which requires manual review before the refund can be issued.
N/A	No refund failure has occurred.