Response

Response schemas and error codes for Ultra Swap API endpoints.

Ultra Swap API is no longer actively maintained and has been superseded by Swap V2.

​

Order Response

Success

Metis

{
    "mode": "ultra",
    "inAmount": "100000000",
    "outAmount": "461208958",
    "otherAmountThreshold": "460024271",
    "swapMode": "ExactIn",
    "slippageBps": 26,
    "priceImpactPct": "-0.0001311599520149334",
    "routePlan": [
        {
        "swapInfo": {
            "ammKey": "HTvjzsfX3yU6BUodCjZ5vZkUrAxMDTrBs3CJaq43ashR",
            "label": "MeteoraDLMM",
            "inputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "outputMint": "So11111111111111111111111111111111111111112",
            "inAmount": "52000000",
            "outAmount": "239879552",
            "feeAmount": "0",
            "feeMint": "11111111111111111111111111111111"
        },
        "percent": 52,
        "bps": 5200
        }
    ],
    "feeMint": "So11111111111111111111111111111111111111112",
    "feeBps": 2,
    "taker": "taker-address",
    "gasless": false,
    "signatureFeeLamports": 5000,
    "transaction": "AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQAEB+r/6dWfRh5QZq1pS2FU/a5CQmMX/HcgLK4+zaeSlI5cZdTk+KNaH68Jj2ISScdmgdJ/88PKxKtXPavfMK2A5TFvQBO6cleTQsKnQWYpDA5PurAceVrkoCVPKJSGBw6LARo6wTdxxXRAzu6pCAqBH8SnExvClVC1O8bT5gyQxm5oAwZGb+UhFzL/7K26csOb57yM5bvF9xJrLEObOkAAAAAEedVb8jHAbu50xW7OaBUH/bGy3qP0jlECsc2iVrwTjwbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpeE6XgwQiPQTdYGYpJIn7N9ynBymyDkUCCC1aA3Klx+cFBAAFAjh+AQAEAAkD75JsAAAAAAAFBQEAFAYQCZPxe2T0hK52/wUhAAIBEhQGBgURBQcWCggLCQwCAQAGFRcADQECDw4DFQYTLrtk+swxxK8UAOH1BQAAAAAbtn0bAAAAABoAAgAAAAIAAABDUBQAAlYB/8ASAAIGAwEAAAEJAym/lQcqT78E33F1k+c4vMwhJygVwkcagNn59VWw1IQlASAFEwAoAhdSojJcrqzlDmuUV2ZVdk3ihN14mZpQMxrnUJS463C7xAUxLhQVMAItL7MrMZDyYzurr+hCn5YjvrvmsR9/EdfdhYUISn5ODzRsA8vPzAHO",
    "prioritizationFeeLamports": 696237,
    "rentFeeLamports": 0,
    "inputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "outputMint": "So11111111111111111111111111111111111111112",
    "swapType": "aggregator",
    "router": "metis",
    "requestId": "019974a8-5fbb-7395-9355-9ebf8f844884",
    "inUsdValue": 99.96761068334662,
    "outUsdValue": 99.95449893632635,
    "priceImpact": -0.013115995201493341,
    "swapUsdValue": 99.96761068334662,
    "totalTime": 359
}

Failed

In cases where it fails to find a quote, the response will be as follows.

400 Response Code

{
    "error": "Failed to get quotes"
}

​

Order Response Codes

In cases where a quote is available but the swap simulation fails, there are error codes that can be returned.

errorCode	errorMessage	Description
1	Insufficient funds	Does not have sufficient swap amount
2	Top up ${solAmount} SOL for gas	Does not have sufficient SOL for gas fees
3	Minimum ${swapAmount} for gasless	Does not have sufficient trade size to be applicable for Gasless Support

​

Execute Response

Success

Use the signature field to view the transaction in an explorer.

{
    "status": "Success",
    "signature": "transaction-signature",
    "slot": "323598314",
    "code": 0,
    "inputAmountResult": "9995000",
    "outputAmountResult": "1274698",
    "swapEvents": [
        {
        "inputMint": "So11111111111111111111111111111111111111112",
        "inputAmount": "9995000",
        "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "outputAmount": "1274698"
        }
    ]
}

Failed

Here are some example cases of the execute response when it fails.

Ultra Endpoint Codes

{
    "code": -1,
    "error": "Order not found, it might have expired"
}

Aggregator Swap Type Codes

{
    "status": "Failed",
    "slot": "0",
    "signature": "transaction-signature",
    "code": -1005,
    "error": "Transaction expired"
}

RFQ Swap Type Codes

{
    "status": "Failed",
    "slot": "0",
    "code": -2005,
    "error": "Internal error",
}

In cases where the routes are of aggregator types like Metis and has been submitted to the network, but failed to land due to program related errors, the response will be as follows.

Only Jupiter V6 Aggregator Program Codes are parsed with description, for other DEX program codes, the error message can be custom program error: #<code>.

Program Related Codes

{
    "status": "Failed",
    "signature": "transaction-signature",
    "slot": "368661931",
    "code": 6001,
    "error": "Slippage tolerance exceeded",
    "totalInputAmount": "1000000",
    "totalOutputAmount": "4647512",
    "inputAmountResult": "1000000",
    "outputAmountResult": "4648441",
    "swapEvents": [
        {
        "inputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "inputAmount": "50000",
        "outputMint": "So11111111111111111111111111111111111111112",
        "outputAmount": "232423"
        },
        {
        "inputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "inputAmount": "950000",
        "outputMint": "So11111111111111111111111111111111111111112",
        "outputAmount": "4416018"
        }
    ]
}

​

Execute Response Codes

Code	Description	Debugging
0	Success	-
-1	Missing cached order	requestId not found in cache, likely expired or not found
-2	Invalid signed transaction	signedTransaction is invalid, likely failed to sign the transaction correctly
-3	Invalid message bytes	signedTransaction is invalid, likely due to incorrect usage like modification of transaction field in the order response
-4	Missing request id	requestId is not found in the request to /execute
-5	Missing signed transaction	signedTransaction is not found in the request to /execute

​

Aggregator Swap Type Codes

Code	Description	Debugging
-1000	Failed to land	Transaction failed to land on the network
-1001	Unknown error	Please try again, if it persists please reach out in Discord
-1002	Invalid transaction	Please try again, if it persists please reach out in Discord
-1003	Transaction not fully signed	Failed to sign the transaction correctly
-1004	Invalid block height	The block height is invalid
-1005	Expired	The submitted transaction has been attempted but has expired
-1006	Timed out	The submitted transaction has been attempted but has timed out
-1007	Gasless unsupported wallet	The wallet is not supported for gasless

​

RFQ Swap Type Codes

Code	Description	Debugging
-2000	Failed to land	Please try again, if it persists please reach out in Discord
-2001	Unknown error	Please try again, if it persists please reach out in Discord
-2002	Invalid payload	Please try again, if it persists please reach out in Discord
-2003	Quote expired	User did not respond in time or RFQ provider did not execute in time
-2004	Swap rejected	User or RFQ provider rejected the swap
-2005	Internal error	Please try again, if it persists please reach out in Discord

​

Program Related Codes

For Jupiter V6 Aggregator Program Codes, the error message will be parsed with description.

IDL

For the full and most up to date list of Jupiter V6 Aggregator Program Codes, you can refer to the IDL on an explorer.

If you need help identifying the other DEX program codes, please reach out in Discord.

​

Best Practices

It is important to understand the error codes to provide a better experience for your users, helping them make an informed decision or follow up step to help their transaction succeed.

See https://jup.ag/ as a reference to understand how we handle errors on the UI.

Example Error	Best Practice
Slippage exceeding threshold	Show the user the current slippage tolerance and the incurred slippage
Insufficient funds	Disable swap widget but still provide quote visibility
Non Jupiter Program Errors	Allow the user to retry with a new route by requoting and/or exclude the specific DEX from the quote request