API v3 error codes #1471
+134
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,133 @@ | ||
| --- | ||
| title: "API v3 error codes" | ||
| --- | ||
|
|
||
| ## Overview | ||
|
|
||
| | Status | Meaning | | ||
| | ------ | ------------------------------ | | ||
| | `401` | Missing required field | | ||
| | `404` | Data not found | | ||
| | `409` | Resource exists but wrong type | | ||
| | `422` | Invalid request parameters | | ||
| | `500` | Server-side failure | | ||
|
|
||
| ## By task | ||
|
|
||
| ### Account & wallet info | ||
|
|
||
| **Endpoints:** `/api/v3/account`, `/api/v3/addressInformation`, `/api/v3/wallet`, `/api/v3/walletInformation`, `/api/v3/accountStates`, `/api/v3/walletStates` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | -------------------------------- | ----------------------------------------------- | | ||
| | `401` | `address of account is required` | Include the `address` parameter | | ||
|
There was a problem hiding this comment. [HIGH] Error strings use code font instead of quotation marksThe error message in the "Account & wallet info" table is rendered as a code span ( Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone! |
||
| | `409` | `not a wallet` | Account exists but isn't a wallet contract | | ||
| | `500` | `balance is none` | Indexer couldn't read balance from stored state | | ||
| | `500` | `status is none` | Indexer couldn't resolve account status | | ||
| | `500` | `last_transaction_hash is none` | No last transaction hash in indexed data | | ||
| | `500` | `last_transaction_lt is none` | No last transaction lt in indexed data | | ||
|
|
||
| ### Sending messages | ||
|
|
||
| **Endpoint:** `/api/v3/message` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | ----------------- | -------------------------------------------- | | ||
| | `401` | `boc is required` | Include a serialized BoC in the request body | | ||
|
|
||
| ### Running get methods | ||
|
|
||
| **Endpoint:** `/api/v3/runGetMethod` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | --------------------- | ------------------------------- | | ||
| | `401` | `address is required` | Include target contract address | | ||
| | `401` | `method is required` | Include the get-method name | | ||
|
|
||
| ### Querying blocks & shards | ||
|
|
||
| **Endpoints:** `/api/v3/masterchainBlockShardState`, `/api/v3/masterchainBlockShards` | ||
|
|
||
| | Status | Error | Meaning | | ||
| | ------ | ------------------ | --------------------------------------- | | ||
| | `404` | `blocks not found` | Block or shard doesn't exist in storage | | ||
|
|
||
| ### Transactions & messages | ||
|
|
||
| **Endpoint:** `/api/v3/transactionsByMessage` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | ----------------------------------------------------------------- | --------------------------- | | ||
| | `422` | `at least one of msg_hash, body_hash, opcode should be specified` | Provide at least one filter | | ||
|
|
||
| ### Pending transactions & traces | ||
|
|
||
| **Endpoints:** `/api/v3/pendingTransactions`, `/api/v3/pendingTraces`, `/api/v3/pendingActions` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | --------------------------------------------------- | ------------------------------------------ | | ||
| | `422` | `at least 1 account address required` | Include at least one account address | | ||
| | `422` | `only one of account, trace_id should be specified` | Use only one filter | | ||
| | `422` | `account or ext_msg_hash should be specified` | Filter by account or external message hash | | ||
| | `500` | `emulatedTracesRepository is not initialized` | Server-side issue | | ||
|
|
||
| ### Traces & events | ||
|
|
||
| **Endpoints:** `/api/v3/traces`, `/api/v3/events` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | ---------------------------------------------------------------------- | --------------------------- | | ||
| | `422` | `only one of account, trace_id, tx_hash, msg_hash should be specified` | Use only one primary filter | | ||
|
|
||
| ### Address book & metadata | ||
|
|
||
| **Endpoints:** `/api/v3/addressBook`, `/api/v3/metadata` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | ----------------------------- | ------------------------------------- | | ||
| | `422` | `at least 1 address required` | Include a non-empty list of addresses | | ||
|
|
||
| ### DNS records | ||
|
|
||
| **Endpoint:** `/api/v3/dns/records` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | --------------------------------------------------- | -------------------------------- | | ||
| | `422` | `either wallet address or domain is required` | Provide wallet address or domain | | ||
| | `422` | `provide either wallet address or domain, not both` | Use one filter, not both | | ||
|
|
||
| ### NFT items | ||
|
|
||
| **Endpoint:** `/api/v3/nft/items` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | ------------------------------------------------------------------ | ------------------------------------------------------------- | | ||
| | `422` | `exact one owner_address required for multiple collection_address` | When querying multiple collections, provide exactly one owner | | ||
|
|
||
| ### Jetton wallets | ||
|
|
||
| **Endpoint:** `/api/v3/jetton/wallets` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | -------------------------------------------------------------- | ---------------------------------------------------------------- | | ||
| | `422` | `exact one owner_address required for multiple jetton_address` | When querying multiple jetton masters, provide exactly one owner | | ||
|
|
||
| ### Multisig | ||
|
|
||
| **Endpoints:** `/api/v3/multisig/wallets`, `/api/v3/multisig/orders` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | ----------------------------------------------------------------- | -------------------------------------------- | | ||
| | `422` | `At least one of address or wallet_address should be specified` | Filter by multisig contract or signer wallet | | ||
| | `422` | `At least one of address or multisig_address should be specified` | Filter by order address or parent multisig | | ||
|
|
||
| ### Decoding | ||
|
|
||
| **Endpoint:** `/api/v3/decode` | ||
|
|
||
| | Status | Error | Fix | | ||
| | ------ | --------------------------------------------- | ---------------------------------------------------------------- | | ||
| | `422` | `opcodes list exceeds maximum length of 1000` | Reduce number of opcodes | | ||
| | `422` | `bodies list exceeds maximum length of 1000` | Reduce number of message bodies | | ||
| | `422` | `invalid opcode format at index %d: %s` | Fix the opcode at specified index (must be valid hex or decimal) | | ||
| | `500` | `marker request failed: <details>` | Internal decode service failed | | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[HIGH] Numeric status columns not right-aligned
In the
Overviewtable, theStatuscolumn header and separator (| Status |/| ------ |) do not specify right alignment, so the numeric HTTP status codes in that column render left-aligned. This violates the documented style rule that numeric columns must be right-aligned for readability and consistency (seecontribute/style-guide-extended.mdx). The same pattern is repeated for all otherStatuscolumns on this page, so the misalignment affects every status code table inv3-errors.mdx. The primary location above points to the first occurrence; other instances share the same structural issue.Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the style guide doesn't fit this one. Left aligned error codes look better IMO
