From 1c3a65b9989a1aa56ab8129eadb020d1fca0e3ba Mon Sep 17 00:00:00 2001 From: YY Date: Fri, 21 Feb 2025 19:14:32 +0800 Subject: [PATCH 1/5] add program error codes --- docs/100-swap-api/program-errors.md | 47 +++++++++++++++++++++++++++++ sidebars-docs.js | 4 +++ 2 files changed, 51 insertions(+) create mode 100644 docs/100-swap-api/program-errors.md diff --git a/docs/100-swap-api/program-errors.md b/docs/100-swap-api/program-errors.md new file mode 100644 index 00000000..f5aa2474 --- /dev/null +++ b/docs/100-swap-api/program-errors.md @@ -0,0 +1,47 @@ +--- +sidebar_label: "Program Errors" +description: "Program errors for the Jupiter Swap Program." +title: "Program Errors" +--- + + + Swap Program Errors + + + +In this section, you can find the list of errors that can be returned by the Jupiter Swap Program. + +:::info Jupiter Swap Program IDL +You can find the full Swap Program IDL here: +https://solscan.io/account/JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4#anchorProgramIdl +::: + +:::tip Other DEX Program Errors +In the swap transaction, the DEX in the routing may return errors. You can find some of their IDLs and/or error codes in an explorer. + +If you need additional help, please reach out to Jupiter Support. +::: + +## Jupiter Swap Program Errors + +| Error Code | Error Name | Description | +| ---------- | ---------- | ----------- | +| 6000 | EmptyRoute | Empty route | +| 6001 | SlippageToleranceExceeded | Slippage tolerance exceeded | +| 6002 | InvalidCalculation | Invalid calculation | +| 6003 | MissingPlatformFeeAccount | Missing platform fee account | +| 6004 | InvalidSlippage | Invalid slippage | +| 6005 | NotEnoughPercent | Not enough percent to 100 | +| 6006 | InvalidInputIndex | Token input index is invalid | +| 6007 | InvalidOutputIndex | Token output index is invalid | +| 6008 | NotEnoughAccountKeys | Not Enough Account keys | +| 6009 | NonZeroMinimumOutAmountNotSupported | Non zero minimum out amount not supported | +| 6010 | InvalidRoutePlan | Invalid route plan | +| 6011 | InvalidReferralAuthority | Invalid referral authority | +| 6012 | LedgerTokenAccountDoesNotMatch | Token account doesn't match the ledger | +| 6013 | InvalidTokenLedger | Invalid token ledger | +| 6014 | IncorrectTokenProgramID | Token program ID is invalid | +| 6015 | TokenProgramNotProvided | Token program not provided | +| 6016 | SwapNotSupported | Swap not supported | +| 6017 | ExactOutAmountNotMatched | Exact out amount doesn't match | +| 6018 | SourceAndDestinationMintCannotBeTheSame | Source mint and destination mint cannot the same | diff --git a/sidebars-docs.js b/sidebars-docs.js index 1a56c40c..da4940e0 100644 --- a/sidebars-docs.js +++ b/sidebars-docs.js @@ -67,6 +67,10 @@ const sidebars = { type: 'doc', id: 'swap-api/send-swap-transaction', }, + { + type: 'doc', + id: 'swap-api/program-errors', + }, ], }, { From 606e0e5590fb526dfc30009c419f71470e4ccf3d Mon Sep 17 00:00:00 2001 From: YY Date: Mon, 24 Feb 2025 23:50:34 +0800 Subject: [PATCH 2/5] update program errors --- docs/100-swap-api/program-errors.md | 71 +++++++++++++++++------------ sidebars-docs.js | 20 ++++++-- 2 files changed, 59 insertions(+), 32 deletions(-) diff --git a/docs/100-swap-api/program-errors.md b/docs/100-swap-api/program-errors.md index f5aa2474..90be2024 100644 --- a/docs/100-swap-api/program-errors.md +++ b/docs/100-swap-api/program-errors.md @@ -9,39 +9,54 @@ title: "Program Errors" -In this section, you can find the list of errors that can be returned by the Jupiter Swap Program. +In this section, you can find the list of errors that can be returned by the Jupiter Swap Program or from other programs like DEXes, System or Token programs. -:::info Jupiter Swap Program IDL +## Solana Program Errors + +| Program | Link | +| ------- | -------------- | +| Token Program | https://github.com/solana-program/token/blob/main/program/src/error.rs | +| Token2022 Program | https://github.com/solana-program/token-2022/blob/main/program/src/error.rs | +| Associated Token Account Program | https://github.com/solana-program/associated-token-account/blob/main/program/src/error.rs | +| Other Solana Programs | https://github.com/solana-program | + +## Jupiter Swap Program Errors + +:::note Jupiter Swap Program IDL You can find the full Swap Program IDL here: https://solscan.io/account/JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4#anchorProgramIdl ::: -:::tip Other DEX Program Errors -In the swap transaction, the DEX in the routing may return errors. You can find some of their IDLs and/or error codes in an explorer. - -If you need additional help, please reach out to Jupiter Support. +:::info Abnormal Error Rates +If you face high or consistent amounts of errors, please reach out to [Jupiter Support](https://jupiverse.zendesk.com/hc/en-us/requests/new?ticket_form_id=18069133114012&tf_18541841140892=api_or_developer_support). ::: -## Jupiter Swap Program Errors - -| Error Code | Error Name | Description | +| Error Code | Error Name | Debug | | ---------- | ---------- | ----------- | -| 6000 | EmptyRoute | Empty route | -| 6001 | SlippageToleranceExceeded | Slippage tolerance exceeded | -| 6002 | InvalidCalculation | Invalid calculation | -| 6003 | MissingPlatformFeeAccount | Missing platform fee account | -| 6004 | InvalidSlippage | Invalid slippage | -| 6005 | NotEnoughPercent | Not enough percent to 100 | -| 6006 | InvalidInputIndex | Token input index is invalid | -| 6007 | InvalidOutputIndex | Token output index is invalid | -| 6008 | NotEnoughAccountKeys | Not Enough Account keys | -| 6009 | NonZeroMinimumOutAmountNotSupported | Non zero minimum out amount not supported | -| 6010 | InvalidRoutePlan | Invalid route plan | -| 6011 | InvalidReferralAuthority | Invalid referral authority | -| 6012 | LedgerTokenAccountDoesNotMatch | Token account doesn't match the ledger | -| 6013 | InvalidTokenLedger | Invalid token ledger | -| 6014 | IncorrectTokenProgramID | Token program ID is invalid | -| 6015 | TokenProgramNotProvided | Token program not provided | -| 6016 | SwapNotSupported | Swap not supported | -| 6017 | ExactOutAmountNotMatched | Exact out amount doesn't match | -| 6018 | SourceAndDestinationMintCannotBeTheSame | Source mint and destination mint cannot the same | +| 6001 | SlippageToleranceExceeded | Try higher fixed slippage or use [`dynamicSlippage`](/docs/swap-api/send-swap-transaction#how-jupiter-estimates-slippage) | +| 6008 | NotEnoughAccountKeys | Likely modified swap transaction causing missing account keys | +| 6014 | IncorrectTokenProgramID | Likely attempted to take platform fees on a Token2022 token | +| 6017 | ExactOutAmountNotMatched | Similar to slippage | + +## DEX Program Errors + +In the swap transaction, the DEX in the routing may return errors. You can find some of their IDLs and/or error codes in an explorer. If they do not support public IDLs or open source code, you can reference the common errors below or if you need additional help, please reach out to [Jupiter Support](https://jupiverse.zendesk.com/hc/en-us/requests/new?ticket_form_id=18069133114012&tf_18541841140892=api_or_developer_support). + +| Error | Description | +| --- | --- | +| Error related to tick array or bitmap extension account | Similar to slippage, the price or market has "moved out of range", hence the swap transaction failed. | + +## Best Practices + +It is important to understand the error codes returned by programs when your products are user facing. This will help you provide a better experience for your users, helping them make an informed decision or follow up step to help their transaction succeed. + + +:::tip Jup.ag as a reference +You can use https://jup.ag/ as a reference to understand how we handle errors on the UI. +::: + +| Error Type | Best Practice | +| ---------- | ------------- | +| Slippage exceeding threshold | Show the user the current slippage tolerance and the incurred slippage | +| Insufficient funds | Show the user the current balance of the account and the required balance | +| Non Jupiter Program Errors | Allow the user to retry with a different route and/or exclude the specific DEX from the quote request | diff --git a/sidebars-docs.js b/sidebars-docs.js index da4940e0..7d74ee06 100644 --- a/sidebars-docs.js +++ b/sidebars-docs.js @@ -67,10 +67,6 @@ const sidebars = { type: 'doc', id: 'swap-api/send-swap-transaction', }, - { - type: 'doc', - id: 'swap-api/program-errors', - }, ], }, { @@ -130,6 +126,22 @@ const sidebars = { type: 'html', value: '
', }, + { + type: 'category', + label: 'Debugging', + collapsible: false, + collapsed: false, + items: [ + { + type: 'doc', + id: 'swap-api/program-errors', + }, + ], + }, + { + type: 'html', + value: '
', + }, ], perp: [ { From b22975c89adf53da0287e31ad101a9d70f60f88e Mon Sep 17 00:00:00 2001 From: YY Date: Tue, 25 Feb 2025 00:38:38 +0800 Subject: [PATCH 3/5] add api responses doc --- docs/api-responses.md | 27 +++++++++++++++++++++++++++ sidebars-docs.js | 2 +- 2 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 docs/api-responses.md diff --git a/docs/api-responses.md b/docs/api-responses.md new file mode 100644 index 00000000..8526e6c3 --- /dev/null +++ b/docs/api-responses.md @@ -0,0 +1,27 @@ +--- +sidebar_label: "API Responses" +description: "API responses for the Jupiter API." +title: "API Responses" +--- + + + API Responses + + + +In this section, you can find the list of responses that can be returned by the Jupiter API. + +:::info Program Errors +For more information on error codes from programs, see the [Swap API - Program Errors](/docs/swap-api/program-errors). +::: + +| Common Codes | Description | Debug | +| --- | --- | --- | +| 200 | Good | Success! | +| 400 | Bad Request | Likely a problem with the request, check the request parameters, syntax, etc. | +| 404 | Not Found | Likely a broken or invalid endpoint. | +| 429 | Rate Limited | You are being rate limited. Either slow down requests, reduce bursts, or upgrade your plan. | +| 500 | Internal Server Error | Please contact [Jupiter Support](https://jupiverse.zendesk.com/hc/en-us/requests/new?ticket_form_id=18069133114012&tf_18541841140892=api_or_developer_support). | +| 502 | Bad Gateway | Please contact [Jupiter Support](https://jupiverse.zendesk.com/hc/en-us/requests/new?ticket_form_id=18069133114012&tf_18541841140892=api_or_developer_support). | +| 503 | Service Unavailable | Please contact [Jupiter Support](https://jupiverse.zendesk.com/hc/en-us/requests/new?ticket_form_id=18069133114012&tf_18541841140892=api_or_developer_support). | +| 504 | Gateway Timeout | Try disabling any proxies, VPNs, firewalls or other network restrictions and try again. If issue persists, please contact [Jupiter Support](https://jupiverse.zendesk.com/hc/en-us/requests/new?ticket_form_id=18069133114012&tf_18541841140892=api_or_developer_support). | diff --git a/sidebars-docs.js b/sidebars-docs.js index 7d74ee06..d97a056f 100644 --- a/sidebars-docs.js +++ b/sidebars-docs.js @@ -13,7 +13,7 @@ const sidebars = { }, { type: 'doc', - id: 'dex-integration', + id: 'api-responses', }, { type: 'html', From 6d559f8f079275c63049cb590bde418d5e1ee288 Mon Sep 17 00:00:00 2001 From: YY Date: Tue, 25 Feb 2025 00:47:03 +0800 Subject: [PATCH 4/5] force api response doc to display doc sidebar --- docs/api-responses.md | 1 + sidebars-docs.js | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/api-responses.md b/docs/api-responses.md index 8526e6c3..020d3686 100644 --- a/docs/api-responses.md +++ b/docs/api-responses.md @@ -2,6 +2,7 @@ sidebar_label: "API Responses" description: "API responses for the Jupiter API." title: "API Responses" +displayed_sidebar: docs --- diff --git a/sidebars-docs.js b/sidebars-docs.js index d97a056f..c7a7f6b9 100644 --- a/sidebars-docs.js +++ b/sidebars-docs.js @@ -136,6 +136,10 @@ const sidebars = { type: 'doc', id: 'swap-api/program-errors', }, + { + type: 'doc', + id: 'api-responses', + }, ], }, { From 7948560ac62f51439d896a5489a34331418f9c65 Mon Sep 17 00:00:00 2001 From: YY Date: Tue, 25 Feb 2025 00:49:24 +0800 Subject: [PATCH 5/5] add api 401 code --- docs/api-responses.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api-responses.md b/docs/api-responses.md index 020d3686..eee8b59b 100644 --- a/docs/api-responses.md +++ b/docs/api-responses.md @@ -20,6 +20,7 @@ For more information on error codes from programs, see the [Swap API - Program E | --- | --- | --- | | 200 | Good | Success! | | 400 | Bad Request | Likely a problem with the request, check the request parameters, syntax, etc. | +| 401 | Unauthorized | Likely a problem with the API key, check if the API key is correct. | | 404 | Not Found | Likely a broken or invalid endpoint. | | 429 | Rate Limited | You are being rate limited. Either slow down requests, reduce bursts, or upgrade your plan. | | 500 | Internal Server Error | Please contact [Jupiter Support](https://jupiverse.zendesk.com/hc/en-us/requests/new?ticket_form_id=18069133114012&tf_18541841140892=api_or_developer_support). |