Jupiter 兑换失败怎么查？先分清 Swap V2、旧 Metis 与链上错误
链小知 · 进阶 · 核验 · 依官方文档整理
以失败记录为输入，按报价构建、签署、提交和链上执行定位问题，避免把不同版本的错误码混用。
开始前准备
- 准备失败时间、两端 mint、输入数量和错误文字。
- 开发者另准备请求路径、router、requestId、errorCode/code；分享时移除 API key 和签名载荷。
- 链上复查需要交易 signature；没有 signature 时不要虚构链上交易。
1. 先判定是哪条产品路径
从应用错误信息或集成请求地址辨认网页流程、Swap V2 的 Meta-Aggregator/Router，还是旧 Metis API。当前 V2 入口为 /swap/v2；旧页中的 6001 等码不能直接套用到所有 V2 结果。
检查结果：记录版本、接口与路由；无法取得版本时保留为待核实。
2. 没有可签交易时先检查 order 响应
V2 的报价不一定附带可用交易：未指定 taker 可只有报价；transaction 为空字符串时应读 router 与 errorCode。相同数值在不同 router 可有不同含义，因此保存二者并查官方表，不靠错误文字模糊匹配。
检查结果：未把有 outAmount 当作已成功构建交易。
3. 核对输入资产与支付费用
检查两端 mint、输入数量最小单位及所用账户。依失败所属版本读取余额或费用不足提示；旧 Metis 的 6024 也涉及交易费用或账户 rent。若依赖 gasless，核对当前路径与条件，而非假定所有订单都能免 SOL。
检查结果：错误定位到输入余额、SOL/账户条件或其他具体类别。
4. 有提交记录时追踪执行结果
对 V2 /execute 查看 status、code 与 signature。官方说明 signature 可以出现在某些失败中，因此收到 signature 后仍要查询该链执行状态。区分未落链、已回滚与已确认，不仅凭接口 HTTP 成功判断成交。
检查结果：status/code 与对应链上结果一致；没有结果时写待确认。
5. 检查有效期、路由和自定义参数
聚合路由按 lastValidBlockHeight 过期，JupiterZ 报价另有 expireAt。过期订单重新取得报价；不要重复使用旧签名载荷。若使用手动参数或改交易，检查是否限制路由、是否缺签署或账户；提高优先费不能修好不兼容交易格式。
检查结果：已核对过期条件与更改参数，未知路由错误没有归为网络拥堵。
6. 成功后按钱包结果字段核算
V2 集成分别读取 totalInputAmount、totalOutputAmount 与 route 的结果字段，核对 feeMint；钱包实际资产变化与路由内部量可能因收费不同。网页用户则以浏览器中的正确 mint 资产变化为准，避免把预计输出截图当回执。
检查结果：记录实际钱包输入输出与费用币种；失败订单没有标作成交。
怎样确认完成
- 能把失败定位到报价、构建、提交或链上执行中的一环。
- 留下足够排查记录且没有暴露凭据、私钥或完整签名载荷。
常见错误与边界
- 把所有错误归因于滑点。
- 只保存错误码，不保存 router 与版本。
- signature 存在就声称兑换成功。