From b9489b2d0848e7108840a26b460ea1d2534015b0 Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Fri, 28 Nov 2025 06:17:42 +0200 Subject: [PATCH 1/4] API v3 error codes --- docs.json | 1 + ecosystem/api/toncenter/v3-errors.mdx | 147 ++++++++++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 ecosystem/api/toncenter/v3-errors.mdx diff --git a/docs.json b/docs.json index 563b6a094..3aef99eaf 100644 --- a/docs.json +++ b/docs.json @@ -73,6 +73,7 @@ "expanded": true, "pages": [ "ecosystem/api/toncenter/get-api-key", + "ecosystem/api/toncenter/v3-errors", { "group": "API v2", "openapi": { diff --git a/ecosystem/api/toncenter/v3-errors.mdx b/ecosystem/api/toncenter/v3-errors.mdx new file mode 100644 index 000000000..bb3c6bc3f --- /dev/null +++ b/ecosystem/api/toncenter/v3-errors.mdx @@ -0,0 +1,147 @@ +--- +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 | +| 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 (Redis misconfig, cold start) | + + +### 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:
` | Internal decode service failed | + From ef2db04899356f2f89f97d5d2ef4e237cda285e2 Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Fri, 28 Nov 2025 06:24:53 +0200 Subject: [PATCH 2/4] fix linting --- ecosystem/api/toncenter/v3-errors.mdx | 134 ++++++++++++-------------- 1 file changed, 60 insertions(+), 74 deletions(-) diff --git a/ecosystem/api/toncenter/v3-errors.mdx b/ecosystem/api/toncenter/v3-errors.mdx index bb3c6bc3f..0225c0bb1 100644 --- a/ecosystem/api/toncenter/v3-errors.mdx +++ b/ecosystem/api/toncenter/v3-errors.mdx @@ -4,14 +4,13 @@ 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 | - +| 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 @@ -19,129 +18,116 @@ title: "API v3 error codes" **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 | -| 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 | - +| Status | Error | Fix | +| ------ | -------------------------------- | ----------------------------------------------- | +| 401 | `address of account is required` | Include the `address` parameter | +| 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 | - +| 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 | - +| 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 | - +| 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 | - +| 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 (Redis misconfig, cold start) | - +| 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 | - +| 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 | - +| 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 | - +| 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 | - +| 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 | - +| 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 | - +| 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:
` | Internal decode service failed | - +| 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:
` | Internal decode service failed | From be9a635b2ada5a12847d8450a5d84a63ab7732e3 Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Fri, 28 Nov 2025 06:26:33 +0200 Subject: [PATCH 3/4] fix linting --- ecosystem/api/toncenter/v3-errors.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ecosystem/api/toncenter/v3-errors.mdx b/ecosystem/api/toncenter/v3-errors.mdx index 0225c0bb1..55a0da187 100644 --- a/ecosystem/api/toncenter/v3-errors.mdx +++ b/ecosystem/api/toncenter/v3-errors.mdx @@ -64,12 +64,12 @@ title: "API v3 error codes" **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 | +| 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 From 8ee77d0aafa4d6fab1483bd9bbd3913517ed93bd Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Mon, 1 Dec 2025 04:19:27 +0200 Subject: [PATCH 4/4] address ai comments --- ecosystem/api/toncenter/v3-errors.mdx | 64 +++++++++++++-------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/ecosystem/api/toncenter/v3-errors.mdx b/ecosystem/api/toncenter/v3-errors.mdx index 55a0da187..be76bf26d 100644 --- a/ecosystem/api/toncenter/v3-errors.mdx +++ b/ecosystem/api/toncenter/v3-errors.mdx @@ -6,11 +6,11 @@ title: "API v3 error codes" | Status | Meaning | | ------ | ------------------------------ | -| 401 | Missing required field | -| 404 | Data not found | -| 409 | Resource exists but wrong type | -| 422 | Invalid request parameters | -| 500 | Server-side failure | +| `401` | Missing required field | +| `404` | Data not found | +| `409` | Resource exists but wrong type | +| `422` | Invalid request parameters | +| `500` | Server-side failure | ## By task @@ -20,12 +20,12 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | -------------------------------- | ----------------------------------------------- | -| 401 | `address of account is required` | Include the `address` parameter | -| 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 | +| `401` | `address of account is required` | Include the `address` parameter | +| `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 @@ -33,7 +33,7 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | ----------------- | -------------------------------------------- | -| 401 | `boc is required` | Include a serialized BoC in the request body | +| `401` | `boc is required` | Include a serialized BoC in the request body | ### Running get methods @@ -41,8 +41,8 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | --------------------- | ------------------------------- | -| 401 | `address is required` | Include target contract address | -| 401 | `method is required` | Include the get-method name | +| `401` | `address is required` | Include target contract address | +| `401` | `method is required` | Include the get-method name | ### Querying blocks & shards @@ -50,7 +50,7 @@ title: "API v3 error codes" | Status | Error | Meaning | | ------ | ------------------ | --------------------------------------- | -| 404 | `blocks not found` | Block or shard doesn't exist in storage | +| `404` | `blocks not found` | Block or shard doesn't exist in storage | ### Transactions & messages @@ -58,7 +58,7 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | ----------------------------------------------------------------- | --------------------------- | -| 422 | `at least one of msg_hash, body_hash, opcode should be specified` | Provide at least one filter | +| `422` | `at least one of msg_hash, body_hash, opcode should be specified` | Provide at least one filter | ### Pending transactions & traces @@ -66,10 +66,10 @@ title: "API v3 error codes" | 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 | +| `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 @@ -77,7 +77,7 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | ---------------------------------------------------------------------- | --------------------------- | -| 422 | `only one of account, trace_id, tx_hash, msg_hash should be specified` | Use only one primary filter | +| `422` | `only one of account, trace_id, tx_hash, msg_hash should be specified` | Use only one primary filter | ### Address book & metadata @@ -85,7 +85,7 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | ----------------------------- | ------------------------------------- | -| 422 | `at least 1 address required` | Include a non-empty list of addresses | +| `422` | `at least 1 address required` | Include a non-empty list of addresses | ### DNS records @@ -93,8 +93,8 @@ title: "API v3 error codes" | 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 | +| `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 @@ -102,7 +102,7 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | ------------------------------------------------------------------ | ------------------------------------------------------------- | -| 422 | `exact one owner_address required for multiple collection_address` | When querying multiple collections, provide exactly one owner | +| `422` | `exact one owner_address required for multiple collection_address` | When querying multiple collections, provide exactly one owner | ### Jetton wallets @@ -110,7 +110,7 @@ title: "API v3 error codes" | Status | Error | Fix | | ------ | -------------------------------------------------------------- | ---------------------------------------------------------------- | -| 422 | `exact one owner_address required for multiple jetton_address` | When querying multiple jetton masters, provide exactly one owner | +| `422` | `exact one owner_address required for multiple jetton_address` | When querying multiple jetton masters, provide exactly one owner | ### Multisig @@ -118,8 +118,8 @@ title: "API v3 error codes" | 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 | +| `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 @@ -127,7 +127,7 @@ title: "API v3 error codes" | 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:
` | Internal decode service failed | +| `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:
` | Internal decode service failed |