From 12e95e33a67e2414e329882b49bc8078f2badf1d Mon Sep 17 00:00:00 2001 From: GiselleNessi Date: Wed, 1 Jul 2026 16:26:02 +0200 Subject: [PATCH 1/4] Add Execution Errors doc for fill and refund failure reasons Documents failReason (57 codes) and refundFailReason (4 codes) as the fill/refund counterpart to the existing quote-errors page. Wired into Core Concepts nav and cross-linked from Handling Quote Errors. --- docs.json | 1 + .../api_core_concepts/execution-errors.mdx | 125 ++++++++++++++++++ .../api/api_core_concepts/handling-errors.mdx | 2 + 3 files changed, 128 insertions(+) create mode 100644 references/api/api_core_concepts/execution-errors.mdx diff --git a/docs.json b/docs.json index 5867696..e22e4f6 100644 --- a/docs.json +++ b/docs.json @@ -91,6 +91,7 @@ "references/api/api_core_concepts/trade-types", "references/api/api_core_concepts/surplus-and-shortage", "references/api/api_core_concepts/handling-errors", + "references/api/api_core_concepts/execution-errors", "references/api/api_core_concepts/contract-compatibility" ] }, diff --git a/references/api/api_core_concepts/execution-errors.mdx b/references/api/api_core_concepts/execution-errors.mdx new file mode 100644 index 0000000..84c3550 --- /dev/null +++ b/references/api/api_core_concepts/execution-errors.mdx @@ -0,0 +1,125 @@ +--- +title: "Handling Execution Errors" +description: "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](/references/api/api_core_concepts/handling-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_ADDRESS_MISMATCH` | The deposit was detected at an address that doesn't match the one issued for this request. | +| `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. | + +### 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 available is too low to refund once fees are applied. | + +### 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 on-chain 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. | +| `JUPITER_INVALID_TOKEN_ACCOUNT` | The token account required for the swap doesn't exist or is invalid (Solana/Jupiter). | + +### On-Chain 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. | + +### 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 on-chain 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. | + +### 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. | +| `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 refund amount is zero or negative before fees, so there's nothing to refund. | +| `NEGATIVE_NEW_AMOUNT_AFTER_FEES` | After deducting fees, the refund amount would be 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. | diff --git a/references/api/api_core_concepts/handling-errors.mdx b/references/api/api_core_concepts/handling-errors.mdx index f97037f..3be3f4c 100644 --- a/references/api/api_core_concepts/handling-errors.mdx +++ b/references/api/api_core_concepts/handling-errors.mdx @@ -5,6 +5,8 @@ description: "Interpret and recover from quote errors in your integration" When calling the `/quote/v2` endpoint, various errors may be returned depending on request conditions, user input, or internal routing logic. This guide outlines the possible error codes, their meanings, and how to handle them. +Looking for errors that occur after a request is submitted? See [Handling Execution Errors](/references/api/api_core_concepts/execution-errors) for fill and refund failure reasons. + ## Expected Errors These are known validation and routing issues that developers should gracefully handle in their integrations: From 302edc34d1970a3800346783a8e8f73e5f41b2c4 Mon Sep 17 00:00:00 2001 From: GiselleNessi Date: Wed, 8 Jul 2026 21:55:42 +0200 Subject: [PATCH 2/4] Address review: remove legacy DEPOSIT_ADDRESS_MISMATCH, fix onchain terminology --- references/api/api_core_concepts/execution-errors.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/references/api/api_core_concepts/execution-errors.mdx b/references/api/api_core_concepts/execution-errors.mdx index 84c3550..a92fd99 100644 --- a/references/api/api_core_concepts/execution-errors.mdx +++ b/references/api/api_core_concepts/execution-errors.mdx @@ -13,7 +13,6 @@ Once a request is submitted, execution can still fail during the fill or, if a f | Error Code | Description | | ---------- | ------------ | -| `DEPOSIT_ADDRESS_MISMATCH` | The deposit was detected at an address that doesn't match the one issued for this request. | | `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. | @@ -41,7 +40,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `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 on-chain swap executed, but the output amount was below the guaranteed minimum. | +| `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. | @@ -55,7 +54,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `INVALID_GAS_PRICE` | The submitted gas price is outside acceptable bounds. | | `JUPITER_INVALID_TOKEN_ACCOUNT` | The token account required for the swap doesn't exist or is invalid (Solana/Jupiter). | -### On-Chain Execution & Revert Errors +### Onchain Execution & Revert Errors | Error Code | Description | | ---------- | ------------ | @@ -79,7 +78,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | Error Code | Description | | ---------- | ------------ | | `ORDER_EXPIRED` | The order's expiration timestamp passed before it could be executed. | -| `ORDER_IS_CANCELLED` | The order was cancelled on-chain before it could be filled. | +| `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. | From 809abf2079120fdcf2b4ddb704bc5165c5dc0071 Mon Sep 17 00:00:00 2001 From: GiselleNessi Date: Wed, 8 Jul 2026 22:16:49 +0200 Subject: [PATCH 3/4] Add 9 fill failure codes from v3 response schema --- references/api/api_core_concepts/execution-errors.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/references/api/api_core_concepts/execution-errors.mdx b/references/api/api_core_concepts/execution-errors.mdx index a92fd99..1aa8244 100644 --- a/references/api/api_core_concepts/execution-errors.mdx +++ b/references/api/api_core_concepts/execution-errors.mdx @@ -19,6 +19,10 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `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 @@ -30,6 +34,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `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 available is too low to refund once fees are applied. | +| `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 @@ -52,6 +57,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `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 @@ -72,6 +78,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `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 @@ -85,6 +92,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `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 @@ -108,6 +116,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | 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. | From e4491c11a2251c6269a40a572eba643bed046ec0 Mon Sep 17 00:00:00 2001 From: GiselleNessi Date: Mon, 13 Jul 2026 16:30:28 +0100 Subject: [PATCH 4/4] Reconcile duplicate error descriptions per review --- references/api/api_core_concepts/execution-errors.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/references/api/api_core_concepts/execution-errors.mdx b/references/api/api_core_concepts/execution-errors.mdx index 1aa8244..b978e5c 100644 --- a/references/api/api_core_concepts/execution-errors.mdx +++ b/references/api/api_core_concepts/execution-errors.mdx @@ -33,7 +33,7 @@ Once a request is submitted, execution can still fail during the fill or, if a f | `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 available is too low to refund once fees are applied. | +| `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 @@ -126,8 +126,8 @@ Once a request is submitted, execution can still fail during the fill or, if a f | Error Code | Description | | ---------- | ------------ | -| `AMOUNT_TOO_LOW_TO_REFUND` | The refund amount is zero or negative before fees, so there's nothing to refund. | -| `NEGATIVE_NEW_AMOUNT_AFTER_FEES` | After deducting fees, the refund amount would be 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. | +| `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. |