Skip to content

Commit 12e95e3

Browse files
GiselleNessiGiselleNessi
committed
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.
1 parent 03aa682 commit 12e95e3

3 files changed

Lines changed: 128 additions & 0 deletions

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@
9191
"references/api/api_core_concepts/trade-types",
9292
"references/api/api_core_concepts/surplus-and-shortage",
9393
"references/api/api_core_concepts/handling-errors",
94+
"references/api/api_core_concepts/execution-errors",
9495
"references/api/api_core_concepts/contract-compatibility"
9596
]
9697
},

‎references/api/api_core_concepts/execution-errors.mdx‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: "Handling Execution Errors"
3+
description: "Interpret fill and refund failure reasons returned after a request has been submitted"
4+
---
5+
6+
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.
7+
8+
## Fill Errors
9+
10+
`failReason` explains why a fill did not complete after a request was submitted.
11+
12+
### Deposit & Validation Errors
13+
14+
| Error Code | Description |
15+
| ---------- | ------------ |
16+
| `DEPOSIT_ADDRESS_MISMATCH` | The deposit was detected at an address that doesn't match the one issued for this request. |
17+
| `DEPOSIT_CHAIN_MISMATCH` | For strict deposit addresses, the deposit landed on a different chain than the one the address was registered for. |
18+
| `INCORRECT_DEPOSIT_CURRENCY` | For strict deposit addresses, the token received doesn't match the currency quoted for this request. |
19+
| `DOUBLE_SPEND` | A second deposit was detected at an address whose first deposit was already processed. |
20+
| `DEPOSITED_AMOUNT_TOO_LOW_TO_FILL` | The amount deposited is less than the quoted amount needed to complete the swap. |
21+
| `ORIGIN_CURRENCY_MISMATCH` | The currency detected on origin doesn't match the origin currency specified in the request. |
22+
| `TTL_EXPIRED` | The request's time-to-live window passed before it could be filled. |
23+
24+
### Solver Capacity & Balance Errors
25+
26+
| Error Code | Description |
27+
| ---------- | ------------ |
28+
| `SOLVER_CAPACITY_EXCEEDED` | The solver's available capacity for this route has been exceeded. |
29+
| `SOLVER_BALANCE_TOO_LOW` | The solver doesn't have enough native tokens or balance to construct the fill transaction. |
30+
| `SPONSOR_BALANCE_TOO_LOW` | The sponsor covering transaction fees doesn't have sufficient balance. |
31+
| `INSUFFICIENT_FUNDS_FOR_RENT` | The user's balance isn't enough to cover rent/storage fees (Solana). |
32+
| `NEGATIVE_NEW_AMOUNT_AFTER_FEES` | After deducting fees, the resulting amount is zero or negative. |
33+
| `AMOUNT_TOO_LOW_TO_REFUND` | The amount available is too low to refund once fees are applied. |
34+
35+
### Swap Routing & Pricing Errors
36+
37+
| Error Code | Description |
38+
| ---------- | ------------ |
39+
| `NO_QUOTES` | No liquidity providers returned a valid quote for this swap at fill time. |
40+
| `NO_INTERNAL_SWAP_ROUTES_FOUND` | No internal DEX route was found between the specified currencies on this chain. |
41+
| `SWAP_IMPACT_TOO_HIGH` | The swap's price impact at fill time exceeds the acceptable threshold. |
42+
| `INSUFFICIENT_POOL_LIQUIDITY` | The DEX pool doesn't have enough reserves to complete the swap at any price. |
43+
| `SLIPPAGE` | The swap couldn't complete within the given slippage tolerance. |
44+
| `TOO_LITTLE_RECEIVED` | The on-chain swap executed, but the output amount was below the guaranteed minimum. |
45+
| `GENERATE_SWAP_FAILED` | Generating the swap transaction (routing, calldata) failed before execution. |
46+
| `REVERSE_SWAP_FAILED` | The reversal swap used to return funds to the user for a refund failed to execute or quote. |
47+
48+
### Transaction Construction & Gas Errors
49+
50+
| Error Code | Description |
51+
| ---------- | ------------ |
52+
| `TRANSACTION_TOO_LARGE` | The serialized transaction exceeds the maximum payload size for the origin chain or RPC. |
53+
| `SWAP_USES_TOO_MUCH_GAS` | The swap transaction would consume more gas than a single block allows. |
54+
| `NEW_CALLDATA_INCLUDES_HIGHER_RENT_FEE` | A refreshed permit increased the rent/storage fee beyond the acceptable limit (Solana). |
55+
| `INVALID_GAS_PRICE` | The submitted gas price is outside acceptable bounds. |
56+
| `JUPITER_INVALID_TOKEN_ACCOUNT` | The token account required for the swap doesn't exist or is invalid (Solana/Jupiter). |
57+
58+
### On-Chain Execution & Revert Errors
59+
60+
| Error Code | Description |
61+
| ---------- | ------------ |
62+
| `EXECUTION_REVERTED` | The swap contract call reverted during execution. |
63+
| `TRANSACTION_REVERTED` | The transaction reverted at the blockchain level. |
64+
| `MISSING_REVERT_DATA` | The transaction reverted, but the reason couldn't be decoded from the returned data. |
65+
| `CONTRACT_PAUSED` | The target contract is currently paused and not accepting calls. |
66+
| `TOKEN_NOT_TRANSFERABLE` | The token enforces a non-transferable restriction (for example, a soulbound token). |
67+
| `TRANSFER_FAILED` | A token transfer reverted at the contract level. |
68+
| `TRANSFER_FROM_FAILED` | Transferring tokens from the user to the contract failed (for example, insufficient allowance). |
69+
| `TRANSFER_AMOUNT_EXCEEDS_ALLOWANCE` | The approved allowance is less than the amount being transferred. |
70+
| `TRANSFER_AMOUNT_EXCEEDS_BALANCE` | The sender's token balance is less than the amount being transferred. |
71+
| `INSUFFICIENT_NATIVE_TOKENS_SUPPLIED` | The native token value supplied with the transaction is less than required. |
72+
| `INCORRECT_PAYMENT` | The value or amount sent doesn't match what the swap requires. |
73+
| `ZERO_SELL_AMOUNT` | The swap was attempted with a zero input amount. |
74+
| `INVALID_SENDER` | The address executing the swap isn't authorized to do so. |
75+
| `INVALID_SIGNER` | The signer on the order doesn't match the address expected by the contract. |
76+
77+
### Order & Signature Errors
78+
79+
| Error Code | Description |
80+
| ---------- | ------------ |
81+
| `ORDER_EXPIRED` | The order's expiration timestamp passed before it could be executed. |
82+
| `ORDER_IS_CANCELLED` | The order was cancelled on-chain before it could be filled. |
83+
| `ORDER_ALREADY_FILLED` | The order was already fully executed and can't be filled again. |
84+
| `SIGNATURE_EXPIRED` | The signature used for token approval expired before execution. |
85+
| `INVALID_SIGNATURE` | The provided signature is invalid or doesn't match the expected signer. |
86+
| `INVALID_NONCE` | The nonce provided has already been used or isn't valid for this signer. |
87+
| `SEAPORT_INEXACT_FRACTION` | The Seaport order specifies a fractional amount that can't be fulfilled exactly. |
88+
| `SEAPORT_INVALID_FULFILLER` | The caller isn't an authorized fulfiller for this Seaport order. |
89+
90+
### Account Abstraction Errors
91+
92+
| Error Code | Description |
93+
| ---------- | ------------ |
94+
| `ACCOUNT_ABSTRACTION_INVALID_NONCE` | The nonce in the account abstraction user operation is invalid or stale. |
95+
| `ACCOUNT_ABSTRACTION_SIGNATURE_ERROR` | The account abstraction user operation's signature is invalid. |
96+
| `ACCOUNT_ABSTRACTION_GAS_LIMIT` | The gas required for account abstraction verification exceeds the allowed limit. |
97+
98+
### NFT Minting Errors
99+
100+
| Error Code | Description |
101+
| ---------- | ------------ |
102+
| `MINT_NOT_ACTIVE` | The NFT mint phase isn't currently active. |
103+
| `ERC_1155_TOO_MANY_REQUESTED` | The quantity requested exceeds the contract's allowed batch size. |
104+
| `MINT_QUANTITY_EXCEEDS_MAX_PER_WALLET` | The wallet has already minted the maximum quantity allowed. |
105+
| `MINT_QUANTITY_EXCEEDS_MAX_SUPPLY` | The requested quantity would exceed the collection's maximum supply. |
106+
107+
### Other
108+
109+
| Error Code | Description |
110+
| ---------- | ------------ |
111+
| `FLUID_DEX_ERROR` | The Fluid DEX protocol returned an error during the swap. |
112+
| `UNKNOWN` | The fill failed for a reason that didn't match a known error pattern. |
113+
| `N/A` | The fill completed without failure. |
114+
115+
## Refund Errors
116+
117+
`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.
118+
119+
| Error Code | Description |
120+
| ---------- | ------------ |
121+
| `AMOUNT_TOO_LOW_TO_REFUND` | The refund amount is zero or negative before fees, so there's nothing to refund. |
122+
| `NEGATIVE_NEW_AMOUNT_AFTER_FEES` | After deducting fees, the refund amount would be zero or negative. |
123+
| `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. |
124+
| `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. |
125+
| `N/A` | No refund failure has occurred. |

‎references/api/api_core_concepts/handling-errors.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: "Interpret and recover from quote errors in your integration"
55

66
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.
77

8+
<Tip>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.</Tip>
9+
810
## Expected Errors
911

1012
These are known validation and routing issues that developers should gracefully handle in their integrations:

0 commit comments

Comments
 (0)