Add Execution Errors doc for fill and refund failure reasons#352
Add Execution Errors doc for fill and refund failure reasons#352GiselleNessi wants to merge 4 commits into
Conversation
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.
|
Claude finished @GiselleNessi's task in 1m 49s —— View job Code Review: Add Execution Errors docNice addition — this fills a real gap as the fill/refund counterpart to the quote-errors page. The nav wiring ( 1. Terminology:
|
| Code | Fill table | Refund table |
|---|---|---|
AMOUNT_TOO_LOW_TO_REFUND |
line 33 — "The amount available is too low to refund once fees are applied." | line 121 — "The refund amount is zero or negative before fees, so there's nothing to refund." |
NEGATIVE_NEW_AMOUNT_AFTER_FEES |
line 32 — "After deducting fees, the resulting amount is zero or negative." | line 122 — "After deducting fees, the refund amount would be zero or negative." |
If these are genuinely returnable as both failReason and refundFailReason, keeping them in both tables is fine — but the two descriptions for the same code should probably be reconciled (they currently read as slightly contradictory for AMOUNT_TOO_LOW_TO_REFUND: "too low once fees applied" vs. "zero or negative before fees"). If they're really only refund reasons, drop them from the Fill table.
Relatedly, AMOUNT_TOO_LOW_TO_REFUND sitting under Solver Capacity & Balance Errors in the Fill section reads oddly — its description is entirely about refunds. Worth double-checking that grouping.
3. Codes shared with the quote-errors page
NO_QUOTES, NO_INTERNAL_SWAP_ROUTES_FOUND, and SWAP_IMPACT_TOO_HIGH also appear on handling-errors.mdx. That's plausible (they can surface both at quote time and fill time), so no change needed — just flagging in case any of them is actually quote-only and slipped in.
4. Author's own flags — still open
You flagged these in the PR description and I couldn't verify them from the docs repo alone (they depend on solver):
REFUND_RECIPIENT_IS_VASP— the description asserts the API returns this literal string, but your note says VASP handling looks like an internalmanualRefundRequiredflag. If the API never surfaces this exactrefundFailReasonvalue, it shouldn't be documented as one.DEPOSIT_ADDRESS_MISMATCH— description is inferred from the name, no throw site found. Confirm againstrelay-kit/protocolbefore merge, or the entry may mislead.
These two are the only correctness risks I'd consider blocking; everything else is polish. Since the descriptions were traced from throw sites, the rest reads as trustworthy.
Overall: clean, well-organized, on-style. Items 1–2 are quick fixes; items 3–4 just need a confirming glance at solver. I can apply the onchain fix and reconcile the duplicate descriptions if you'd like — just say the word.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
VASP is Virtual Asset Service Provider, it is returned in the API. Let's omit DEPOSIT_ADDRESS_MISMATCH, looks like legacy error code. |
|
Pushed fixes: removed Update: Checking that schema also surfaced 9 newer fill codes that were missing from the doc — added in 809abf2. Both tables now match the v3 enums exactly. |
|
Claude finished @GiselleNessi's task in 1m 44s —— View job Code Review: Add Execution Errors doc — PR #352Re-reviewed after the latest push. Confirming what's resolved and flagging the one item still open. ✅ Resolved since last review
🟡 Still open — duplicate codes across Fill and Refund tables
"once fees are applied" vs. "before fees" point in opposite directions for the same code. Two things to settle:
Since you traced these from throw sites in Style/structure checks — all pass
Overall: clean and on-style; three of four prior items are resolved. The only thing I'd settle before merge is the |
|
Claude finished @GiselleNessi's task in 1m 4s —— View job Code Review: Add Execution Errors doc — PR #352Re-reviewed the current state of the branch (after ✅ Resolved
🟡 Still open —
|
| Location | Description |
|---|---|
Fill table (execution-errors.mdx:36) |
"The amount available is too low to refund once fees are applied." |
Refund table (execution-errors.mdx:129) |
"The refund amount is zero or negative before fees, so there's nothing to refund." |
Two things to settle:
- Reconcile the wording — "once fees are applied" vs. "before fees" describe different conditions for the same code.
- Confirm the Fill-table placement — a code named
AMOUNT_TOO_LOW_TO_REFUND, described entirely in refund terms, sitting under Solver Capacity & Balance Errors in the Fill section reads oddly. If it genuinely surfaces as afailReason, its Fill-table row should describe the fill-side condition; if it's refund-only, drop it from the Fill table.
Since you traced these from throw sites, you're best placed to confirm whether it returns as both failReason and refundFailReason or only the latter.
Minor — NEGATIVE_NEW_AMOUNT_AFTER_FEES dual listing
Also in both tables (:35 fill, :130 refund). The two descriptions are consistent (just fill vs. refund framing), so no contradiction — but the same question applies: confirm it truly surfaces as both a failReason and a refundFailReason. If yes, no change needed.
Style/structure — all pass
- Frontmatter
title+ verb-firstdescriptionpresent (§2.1). ✅ - Heading depth stays
##/###(§2.2). ✅ - Follows §3.3a API-concept profile (feature-guide shape, terse intro, no Requirements). ✅
Error Code | Descriptiontable format matches thehandling-errors.mdxexemplar. ✅- Nav wiring correct —
execution-errorssits right afterhandling-errorsindocs.json, with the reciprocal cross-link<Tip>on both pages (handling-errors.mdx:8). ✅ - Terminology consistent —
onchain,cross-chain, chain/token casing all match §5. ✅ - Shared codes with the quote-errors page (
NO_QUOTES,NO_INTERNAL_SWAP_ROUTES_FOUND,SWAP_IMPACT_TOO_HIGH) plausibly surface at both quote and fill time — no change needed.
Overall: clean and on-style. The only substantive item before merge is the AMOUNT_TOO_LOW_TO_REFUND wording/placement — a quick solver check settles it. This was a review request, so I made no changes; happy to apply the reconciliation if you'd like.
• giselle/int2-734-add-execution-errors-to-docs
|
Claude finished @GiselleNessi's task in 56s —— View job Code Review: Add Execution Errors doc — PR #352Re-reviewed the current branch state. The page is clean, well-organized, and on-style. Three of the four prior items are resolved; one substantive item remains. ✅ Resolved
🟡 Still open —
|
| Location | Description |
|---|---|
Fill table (execution-errors.mdx:36) |
"The amount available is too low to refund once fees are applied." |
Refund table (execution-errors.mdx:129) |
"The refund amount is zero or negative before fees, so there's nothing to refund." |
Two things to settle:
- Reconcile the wording — "once fees are applied" vs. "before fees" describe different conditions for the same code.
- Confirm the Fill-table placement — a code named
AMOUNT_TOO_LOW_TO_REFUND, described entirely in refund terms, sitting under Solver Capacity & Balance Errors in the Fill section reads oddly. If it genuinely surfaces as afailReason, its Fill-table row should describe the fill-side condition; if it's refund-only, drop it from the Fill table.
Since you traced these from throw sites, you're best placed to confirm whether it returns as both failReason and refundFailReason or only the latter. (I can't verify from the docs repo — this needs a solver glance.)
Minor — NEGATIVE_NEW_AMOUNT_AFTER_FEES dual listing
Also in both tables (:35 fill, :130 refund). The two descriptions are consistent (just fill vs. refund framing), so no contradiction — but the same question applies: confirm it truly surfaces as both a failReason and a refundFailReason. If yes, no change needed.
Style/structure — all pass
- Frontmatter
title+ verb-firstdescriptionpresent (§2.1). ✅ - Heading depth stays
##/###(§2.2). ✅ - Follows the §3.3a API-concept profile (feature-guide shape, terse intro, no Requirements). ✅
Error Code | Descriptiontable format matches thehandling-errors.mdxexemplar. ✅- Nav wiring correct —
execution-errorssits right afterhandling-errors(docs.json:96), with the reciprocal cross-link<Tip>on both pages (handling-errors.mdx:8). ✅ - Terminology consistent —
onchain,cross-chain, chain/token casing all match §5. ✅ - Shared codes with the quote-errors page (
NO_QUOTES,NO_INTERNAL_SWAP_ROUTES_FOUND,SWAP_IMPACT_TOO_HIGH) plausibly surface at both quote and fill time — no change needed.
Overall: clean and on-style. The only substantive item before merge is the AMOUNT_TOO_LOW_TO_REFUND wording/placement — a quick solver check settles it. This was a review request, so I made no changes; happy to apply the reconciliation if you'd like.
2 participants
Summary
failReason(fill, 57 codes) andrefundFailReason(refund, 4 codes), as the fill/refund counterpart to the existing quote-errors page.solver.Flags for review
REFUND_RECIPIENT_IS_VASP— couldn't find this as a literalrefundFailReasonvalue in solver; VASP blocks look like they're handled as amanualRefundRequiredflag internally. Description is based on that logic — please confirm the API actually returns this string.DEPOSIT_ADDRESS_MISMATCH— no throw site found in solver (may live in relay-kit/protocol). Description is inferred from naming convention, not verified against code.Closes INT2-734.