# Jupiter 兑换失败怎么查？先分清 Swap V2、旧 Metis 与链上错误

整理：链小知（AI 辅助）
资料核对日期：2026-10-11
引用地址：https://lianxiaozhi.com/tools/guides/jupiter-swap-failed-version-error-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

以失败记录为输入，按报价构建、签署、提交和链上执行定位问题，避免把不同版本的错误码混用。

## 使用工具
- [Jupiter](https://lianxiaozhi.com/tools/jupiter) · [官方入口](https://jup.ag/)

## 前置条件
- 准备失败时间、两端 mint、输入数量和错误文字。
- 开发者另准备请求路径、router、requestId、errorCode/code；分享时移除 API key 和签名载荷。
- 链上复查需要交易 signature；没有 signature 时不要虚构链上交易。

## 1. 先判定是哪条产品路径

从应用错误信息或集成请求地址辨认网页流程、Swap V2 的 Meta-Aggregator/Router，还是旧 Metis API。当前 V2 入口为 /swap/v2；旧页中的 6001 等码不能直接套用到所有 V2 结果。

核对结果：记录版本、接口与路由；无法取得版本时保留为待核实。
依据：[Jupiter：Swap V2 路径及要求](https://developers.jup.ag/docs/swap)
依据：[Jupiter：旧 Metis Swap API 常见错误](https://developers.jup.ag/docs/swap/v1/common-errors)

## 2. 没有可签交易时先检查 order 响应

V2 的报价不一定附带可用交易：未指定 taker 可只有报价；transaction 为空字符串时应读 router 与 errorCode。相同数值在不同 router 可有不同含义，因此保存二者并查官方表，不靠错误文字模糊匹配。

核对结果：未把有 outAmount 当作已成功构建交易。
依据：[Jupiter：Order & Execute 错误、有效期与成交字段](https://developers.jup.ag/docs/swap/order-and-execute)

## 3. 核对输入资产与支付费用

检查两端 mint、输入数量最小单位及所用账户。依失败所属版本读取余额或费用不足提示；旧 Metis 的 6024 也涉及交易费用或账户 rent。若依赖 gasless，核对当前路径与条件，而非假定所有订单都能免 SOL。

核对结果：错误定位到输入余额、SOL/账户条件或其他具体类别。
依据：[Jupiter：旧 Metis Swap API 常见错误](https://developers.jup.ag/docs/swap/v1/common-errors)
依据：[Jupiter：Swap V2 路径及要求](https://developers.jup.ag/docs/swap)

## 4. 有提交记录时追踪执行结果

对 V2 /execute 查看 status、code 与 signature。官方说明 signature 可以出现在某些失败中，因此收到 signature 后仍要查询该链执行状态。区分未落链、已回滚与已确认，不仅凭接口 HTTP 成功判断成交。

核对结果：status/code 与对应链上结果一致；没有结果时写待确认。
依据：[Jupiter：Order & Execute 错误、有效期与成交字段](https://developers.jup.ag/docs/swap/order-and-execute)

## 5. 检查有效期、路由和自定义参数

聚合路由按 lastValidBlockHeight 过期，JupiterZ 报价另有 expireAt。过期订单重新取得报价；不要重复使用旧签名载荷。若使用手动参数或改交易，检查是否限制路由、是否缺签署或账户；提高优先费不能修好不兼容交易格式。

核对结果：已核对过期条件与更改参数，未知路由错误没有归为网络拥堵。
依据：[Jupiter：Order & Execute 错误、有效期与成交字段](https://developers.jup.ag/docs/swap/order-and-execute)

## 6. 成功后按钱包结果字段核算

V2 集成分别读取 totalInputAmount、totalOutputAmount 与 route 的结果字段，核对 feeMint；钱包实际资产变化与路由内部量可能因收费不同。网页用户则以浏览器中的正确 mint 资产变化为准，避免把预计输出截图当回执。

核对结果：记录实际钱包输入输出与费用币种；失败订单没有标作成交。
依据：[Jupiter：Order & Execute 错误、有效期与成交字段](https://developers.jup.ag/docs/swap/order-and-execute)

## 常见错误
- 把所有错误归因于滑点。
- 只保存错误码，不保存 router 与版本。
- signature 存在就声称兑换成功。

## 完成检查
- 能把失败定位到报价、构建、提交或链上执行中的一环。
- 留下足够排查记录且没有暴露凭据、私钥或完整签名载荷。

## 相关知识
- [Solana 交易过期是什么？收到签名不代表执行完成](https://lianxiaozhi.com/learn/solana-transaction-expiry)
- [Solana 钱包地址、mint 与 Token Account 有什么区别？](https://lianxiaozhi.com/learn/solana-token-accounts)
- [Solana 优先费怎样算？Compute Unit 上限也会影响费用](https://lianxiaozhi.com/learn/solana-priority-fees)

## 官方依据
- [Jupiter：Swap V2 路径及要求](https://developers.jup.ag/docs/swap)
- [Jupiter：Order & Execute 错误、有效期与成交字段](https://developers.jup.ag/docs/swap/order-and-execute)
- [Jupiter：旧 Metis Swap API 常见错误](https://developers.jup.ag/docs/swap/v1/common-errors)