From abe0e0869b9e9eecf7777bf7f636cb6b162ea4f4 Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Fri, 28 Nov 2025 06:15:21 +0200 Subject: [PATCH 1/4] API v2 error codes --- docs.json | 1 + ecosystem/api/toncenter/v2-errors.mdx | 185 ++++++++++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 ecosystem/api/toncenter/v2-errors.mdx diff --git a/docs.json b/docs.json index 563b6a094..fb8ca82d6 100644 --- a/docs.json +++ b/docs.json @@ -73,6 +73,7 @@ "expanded": true, "pages": [ "ecosystem/api/toncenter/get-api-key", + "ecosystem/api/toncenter/v2-errors", { "group": "API v2", "openapi": { diff --git a/ecosystem/api/toncenter/v2-errors.mdx b/ecosystem/api/toncenter/v2-errors.mdx new file mode 100644 index 000000000..a6e26a7e8 --- /dev/null +++ b/ecosystem/api/toncenter/v2-errors.mdx @@ -0,0 +1,185 @@ +--- +title: "API v2 error codes" +--- + +## Overview + +| Status | Meaning | +|--------|---------| +| 404 | Data not found | +| 405 | Wrong HTTP method (use GET or POST) | +| 409 | Resource exists but wrong type | +| 422 | Invalid request parameters | +| 429 | Rate limit exceeded | +| 500 | Server-side failure | +| 504 | Timeout waiting for liteserver | +| 542 | Liteserver-specific error or unsupported stack type | + +--- + +## By task + +### Sending transactions + +**Endpoint:** `/api/v2/sendBoc`, `/api/v2/sendBocReturnHash` + +| Status | Error | Fix | +|--------|-------|-----| +| 422 | `empty boc` | Include a non-empty `boc` field in request body | +| 429 | `Ratelimit exceeded` | Back off and retry | +| 500 | `Exit code != 0` | Transaction simulation failed, check your BOC | +| 504 | `LITE_SERVER_NETWORK timeout...` | Liteserver didn't respond in time, retry | + +--- + +### Querying transactions + +**Endpoints:** `/api/v2/getTransactions`, `/api/v2/tryLocateTx`, `/api/v2/tryLocateResultTx`, `/api/v2/tryLocateSourceTx` + +| Status | Error | Fix | +|--------|-------|-----| +| 404 | `transaction not found` | No matching transaction exists for that source/destination/lt | +| 422 | `failed to parse address` | Address format is invalid | +| 422 | `failed to parse hash` | Hash format is invalid | +| 422 | `failed to parse lt` / `failed to parse created_lt` | Not a valid 64-bit integer | +| 422 | `lt should be non-negative` / `created_lt should be non-negative` | Value can't be negative | +| 422 | `lt and hash should be used together` | Provide both or neither | +| 422 | `empty source address` / `empty destination address` | Required parameter is missing | +| 422 | `limit should be positive` | Must be ≥ 1 | +| 422 | `limit should be less or equal 1000` | Max is 1000 | + +--- + +### Querying addresses & balances + +**Endpoint:** `/api/v2/getAddressBalance` + +| Status | Error | Fix | +|--------|-------|-----| +| 422 | `empty address` | Include the `address` parameter | +| 422 | `failed to parse seqno` | Not a valid integer | +| 422 | `seqno should be positive` | Must be ≥ 1 | + +--- + +### Querying blocks + +**Endpoints:** `/api/v2/getBlockHeader`, `/api/v2/getBlockTransactionsExt`, `/api/v2/getShardBlockProof`, `/api/v2/lookupBlock` + +| Status | Error | Fix | +|--------|-------|-----| +| 422 | `workchain required` | Include `workchain` parameter | +| 422 | `shard required` | Include `shard` parameter | +| 422 | `seqno required` | Include `seqno` parameter | +| 422 | `failed to parse workchain` | Not a valid integer | +| 422 | `failed to parse shard` | Not a valid shard identifier | +| 422 | `failed to parse root_hash` | Not a valid 256-bit hash | +| 422 | `failed to parse seqno` | Not a valid integer | +| 422 | `seqno should be positive` | Must be ≥ 1 | +| 422 | `from_seqno should be non-negative` | Can't be negative | +| 422 | `exactly one of seqno, lt, unixtime should be specified` | Provide exactly one selector | +| 422 | `lt should be non-negative` / `unixtime should be non-negative` | Can't be negative | +| 422 | `after_lt and after_hash should be used together` | Provide both or neither | +| 422 | `after_lt should be non-negative` | Can't be negative | +| 422 | `count should be positive` | Must be ≥ 1 | +| 422 | `count should be less or equal 10000` | Max is 10,000 | + +--- + +### Running get methods + +**Endpoints:** `/api/v2/runGetMethod`, `/api/v2/runGetMethodStd` + +#### Request validation (422) + +| Error | Fix | +|-------|-----| +| `Stack should be array` / `Invalid stack format: array expected` | `stack` must be a JSON array | +| `Invalid stack entry format: array of exact 2 elements expected` | Each entry needs `[type, value]` | +| `Invalid stack entry format: invalid type ` | Use valid types: `num`, `cell`, `slice`, etc. | +| `Invalid stack entry format: base64 string expected` | Cell/slice values must be base64 | +| `Invalid tvm.Cell, base64 string expected` / `Invalid tvm.Slice, base64 string expected` | Use base64 encoding | +| `Invalid cell, object with field bytes expected` / `Invalid slice, object with field bytes expected` | Object must have `bytes` field | +| `Empty tvm.Cell` / `Empty tvm.Slice` / `Empty cell` / `Empty slice` | Value can't be empty | +| `Invalid tvm.List, valid tvm_stackEntryList expected` | Malformed list entry | +| `Invalid tvm.Tuple, valid tvm_stackEntryTuple expected` | Malformed tuple entry | +| `Expected string as first element in stack entry` | First element must be type tag string | +| `Wrong type of number in stack entry` | Number format is wrong | + +#### Execution errors (500) + +| Error | Meaning | +|-------|---------| +| `Exit code != 0` | Get method returned non-zero exit code | +| `Stack size < 5` | Contract returned fewer values than expected | +| `Failed to parse int: ` | Couldn't parse numeric result | +| `stackEntryNumber expected` / `stackEntryNumber expected at 0 position` | Expected number, got something else | +| `stackEntryCell expected at position` | Expected cell at that stack position | +| `stackEntryCell or stackEntrySlice expected` | Expected cell or slice, got something else | +| `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Address type not supported by converter | + +#### Unsupported types (542) + +| Error | Meaning | +|-------|---------| +| `Unsupported stack entry type: ` | Server can't decode this stack type | + +--- + +### Estimating fees + +**Endpoint:** `/api/v2/estimateFee` + +Same stack/cell/slice validation as get methods (422), plus: + +| Status | Error | Meaning | +|--------|-------|---------| +| 500 | `Exit code != 0` | Simulation failed | +| 500 | `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Unsupported address type | + +--- + +### Token & NFT data + +**Endpoint:** `/api/v2/getTokenData` + +| Status | Error | Meaning | +|--------|-------|---------| +| 409 | `Smart contract
is not Jetton or NFT` | Contract doesn't implement Jetton/NFT interface | +| 500 | `Failed to unpack token data` | Couldn't decode metadata cell | +| 500 | `Invalid uri` / `missing uri field in offchain data` | Metadata URI is missing or malformed | +| 500 | `failed to serialize TokenData` | Internal serialization error | +| 500 | `Exit code != 0` | Get method failed | +| 500 | `Stack size < 5` | Not enough return values | + +--- + +### Config parameters + +**Endpoint:** `/api/v2/getConfigParam` + +| Status | Error | Fix | +|--------|-------|-----| +| 422 | `failed to parse config_id` / `failed to parse param` | Not a valid integer | +| 422 | `only one of config_id or param should be specified` | Use one or the other, not both | +| 422 | `param should be non-negative` | Can't be negative | + +--- + +### Libraries + +**Endpoint:** `/api/v2/getLibraries` + +| Status | Error | Fix | +|--------|-------|-----| +| 422 | `failed to parse libraries` | Must be a valid JSON array of library IDs | + +--- + +### JSON-RPC + +**Endpoint:** `/api/v2/jsonRPC` + +| Status | Error | Fix | +|--------|-------|-----| +| 422 | `params must contain an object` | `params` must be a single JSON object, not an array | From 428b49cc83cf3f7dd38736b5ab022af811d6d8ea Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Fri, 28 Nov 2025 06:20:05 +0200 Subject: [PATCH 2/4] fix linting --- ecosystem/api/toncenter/v2-errors.mdx | 192 +++++++++++++------------- 1 file changed, 96 insertions(+), 96 deletions(-) diff --git a/ecosystem/api/toncenter/v2-errors.mdx b/ecosystem/api/toncenter/v2-errors.mdx index a6e26a7e8..7899feb8e 100644 --- a/ecosystem/api/toncenter/v2-errors.mdx +++ b/ecosystem/api/toncenter/v2-errors.mdx @@ -4,16 +4,16 @@ title: "API v2 error codes" ## Overview -| Status | Meaning | -|--------|---------| -| 404 | Data not found | -| 405 | Wrong HTTP method (use GET or POST) | -| 409 | Resource exists but wrong type | -| 422 | Invalid request parameters | -| 429 | Rate limit exceeded | -| 500 | Server-side failure | -| 504 | Timeout waiting for liteserver | -| 542 | Liteserver-specific error or unsupported stack type | +| Status | Meaning | +| ------ | --------------------------------------------------- | +| 404 | Data not found | +| 405 | Wrong HTTP method (use GET or POST) | +| 409 | Resource exists but wrong type | +| 422 | Invalid request parameters | +| 429 | Rate limit exceeded | +| 500 | Server-side failure | +| 504 | Timeout waiting for liteserver | +| 542 | Liteserver-specific error or unsupported stack type | --- @@ -23,12 +23,12 @@ title: "API v2 error codes" **Endpoint:** `/api/v2/sendBoc`, `/api/v2/sendBocReturnHash` -| Status | Error | Fix | -|--------|-------|-----| -| 422 | `empty boc` | Include a non-empty `boc` field in request body | -| 429 | `Ratelimit exceeded` | Back off and retry | -| 500 | `Exit code != 0` | Transaction simulation failed, check your BOC | -| 504 | `LITE_SERVER_NETWORK timeout...` | Liteserver didn't respond in time, retry | +| Status | Error | Fix | +| ------ | -------------------------------- | ----------------------------------------------- | +| 422 | `empty boc` | Include a non-empty `boc` field in request body | +| 429 | `Ratelimit exceeded` | Back off and retry | +| 500 | `Exit code != 0` | Transaction simulation failed, check your BOC | +| 504 | `LITE_SERVER_NETWORK timeout...` | Liteserver didn't respond in time, retry | --- @@ -36,17 +36,17 @@ title: "API v2 error codes" **Endpoints:** `/api/v2/getTransactions`, `/api/v2/tryLocateTx`, `/api/v2/tryLocateResultTx`, `/api/v2/tryLocateSourceTx` -| Status | Error | Fix | -|--------|-------|-----| -| 404 | `transaction not found` | No matching transaction exists for that source/destination/lt | -| 422 | `failed to parse address` | Address format is invalid | -| 422 | `failed to parse hash` | Hash format is invalid | -| 422 | `failed to parse lt` / `failed to parse created_lt` | Not a valid 64-bit integer | -| 422 | `lt should be non-negative` / `created_lt should be non-negative` | Value can't be negative | -| 422 | `lt and hash should be used together` | Provide both or neither | -| 422 | `empty source address` / `empty destination address` | Required parameter is missing | -| 422 | `limit should be positive` | Must be ≥ 1 | -| 422 | `limit should be less or equal 1000` | Max is 1000 | +| Status | Error | Fix | +| ------ | ----------------------------------------------------------------- | ------------------------------------------------------------- | +| 404 | `transaction not found` | No matching transaction exists for that source/destination/lt | +| 422 | `failed to parse address` | Address format is invalid | +| 422 | `failed to parse hash` | Hash format is invalid | +| 422 | `failed to parse lt` / `failed to parse created_lt` | Not a valid 64-bit integer | +| 422 | `lt should be non-negative` / `created_lt should be non-negative` | Value can't be negative | +| 422 | `lt and hash should be used together` | Provide both or neither | +| 422 | `empty source address` / `empty destination address` | Required parameter is missing | +| 422 | `limit should be positive` | Must be ≥ 1 | +| 422 | `limit should be less or equal 1000` | Max is 1000 | --- @@ -54,11 +54,11 @@ title: "API v2 error codes" **Endpoint:** `/api/v2/getAddressBalance` -| Status | Error | Fix | -|--------|-------|-----| -| 422 | `empty address` | Include the `address` parameter | -| 422 | `failed to parse seqno` | Not a valid integer | -| 422 | `seqno should be positive` | Must be ≥ 1 | +| Status | Error | Fix | +| ------ | -------------------------- | ------------------------------- | +| 422 | `empty address` | Include the `address` parameter | +| 422 | `failed to parse seqno` | Not a valid integer | +| 422 | `seqno should be positive` | Must be ≥ 1 | --- @@ -66,23 +66,23 @@ title: "API v2 error codes" **Endpoints:** `/api/v2/getBlockHeader`, `/api/v2/getBlockTransactionsExt`, `/api/v2/getShardBlockProof`, `/api/v2/lookupBlock` -| Status | Error | Fix | -|--------|-------|-----| -| 422 | `workchain required` | Include `workchain` parameter | -| 422 | `shard required` | Include `shard` parameter | -| 422 | `seqno required` | Include `seqno` parameter | -| 422 | `failed to parse workchain` | Not a valid integer | -| 422 | `failed to parse shard` | Not a valid shard identifier | -| 422 | `failed to parse root_hash` | Not a valid 256-bit hash | -| 422 | `failed to parse seqno` | Not a valid integer | -| 422 | `seqno should be positive` | Must be ≥ 1 | -| 422 | `from_seqno should be non-negative` | Can't be negative | -| 422 | `exactly one of seqno, lt, unixtime should be specified` | Provide exactly one selector | -| 422 | `lt should be non-negative` / `unixtime should be non-negative` | Can't be negative | -| 422 | `after_lt and after_hash should be used together` | Provide both or neither | -| 422 | `after_lt should be non-negative` | Can't be negative | -| 422 | `count should be positive` | Must be ≥ 1 | -| 422 | `count should be less or equal 10000` | Max is 10,000 | +| Status | Error | Fix | +| ------ | --------------------------------------------------------------- | ----------------------------- | +| 422 | `workchain required` | Include `workchain` parameter | +| 422 | `shard required` | Include `shard` parameter | +| 422 | `seqno required` | Include `seqno` parameter | +| 422 | `failed to parse workchain` | Not a valid integer | +| 422 | `failed to parse shard` | Not a valid shard identifier | +| 422 | `failed to parse root_hash` | Not a valid 256-bit hash | +| 422 | `failed to parse seqno` | Not a valid integer | +| 422 | `seqno should be positive` | Must be ≥ 1 | +| 422 | `from_seqno should be non-negative` | Can't be negative | +| 422 | `exactly one of seqno, lt, unixtime should be specified` | Provide exactly one selector | +| 422 | `lt should be non-negative` / `unixtime should be non-negative` | Can't be negative | +| 422 | `after_lt and after_hash should be used together` | Provide both or neither | +| 422 | `after_lt should be non-negative` | Can't be negative | +| 422 | `count should be positive` | Must be ≥ 1 | +| 422 | `count should be less or equal 10000` | Max is 10,000 | --- @@ -92,36 +92,36 @@ title: "API v2 error codes" #### Request validation (422) -| Error | Fix | -|-------|-----| -| `Stack should be array` / `Invalid stack format: array expected` | `stack` must be a JSON array | -| `Invalid stack entry format: array of exact 2 elements expected` | Each entry needs `[type, value]` | -| `Invalid stack entry format: invalid type ` | Use valid types: `num`, `cell`, `slice`, etc. | -| `Invalid stack entry format: base64 string expected` | Cell/slice values must be base64 | -| `Invalid tvm.Cell, base64 string expected` / `Invalid tvm.Slice, base64 string expected` | Use base64 encoding | -| `Invalid cell, object with field bytes expected` / `Invalid slice, object with field bytes expected` | Object must have `bytes` field | -| `Empty tvm.Cell` / `Empty tvm.Slice` / `Empty cell` / `Empty slice` | Value can't be empty | -| `Invalid tvm.List, valid tvm_stackEntryList expected` | Malformed list entry | -| `Invalid tvm.Tuple, valid tvm_stackEntryTuple expected` | Malformed tuple entry | -| `Expected string as first element in stack entry` | First element must be type tag string | -| `Wrong type of number in stack entry` | Number format is wrong | +| Error | Fix | +| ---------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| `Stack should be array` / `Invalid stack format: array expected` | `stack` must be a JSON array | +| `Invalid stack entry format: array of exact 2 elements expected` | Each entry needs `[type, value]` | +| `Invalid stack entry format: invalid type ` | Use valid types: `num`, `cell`, `slice`, etc. | +| `Invalid stack entry format: base64 string expected` | Cell/slice values must be base64 | +| `Invalid tvm.Cell, base64 string expected` / `Invalid tvm.Slice, base64 string expected` | Use base64 encoding | +| `Invalid cell, object with field bytes expected` / `Invalid slice, object with field bytes expected` | Object must have `bytes` field | +| `Empty tvm.Cell` / `Empty tvm.Slice` / `Empty cell` / `Empty slice` | Value can't be empty | +| `Invalid tvm.List, valid tvm_stackEntryList expected` | Malformed list entry | +| `Invalid tvm.Tuple, valid tvm_stackEntryTuple expected` | Malformed tuple entry | +| `Expected string as first element in stack entry` | First element must be type tag string | +| `Wrong type of number in stack entry` | Number format is wrong | #### Execution errors (500) -| Error | Meaning | -|-------|---------| -| `Exit code != 0` | Get method returned non-zero exit code | -| `Stack size < 5` | Contract returned fewer values than expected | -| `Failed to parse int: ` | Couldn't parse numeric result | -| `stackEntryNumber expected` / `stackEntryNumber expected at 0 position` | Expected number, got something else | -| `stackEntryCell expected at position` | Expected cell at that stack position | -| `stackEntryCell or stackEntrySlice expected` | Expected cell or slice, got something else | -| `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Address type not supported by converter | +| Error | Meaning | +| -------------------------------------------------------------------------------------- | -------------------------------------------- | +| `Exit code != 0` | Get method returned non-zero exit code | +| `Stack size < 5` | Contract returned fewer values than expected | +| `Failed to parse int: ` | Couldn't parse numeric result | +| `stackEntryNumber expected` / `stackEntryNumber expected at 0 position` | Expected number, got something else | +| `stackEntryCell expected at position` | Expected cell at that stack position | +| `stackEntryCell or stackEntrySlice expected` | Expected cell or slice, got something else | +| `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Address type not supported by converter | #### Unsupported types (542) -| Error | Meaning | -|-------|---------| +| Error | Meaning | +| -------------------------------------- | ----------------------------------- | | `Unsupported stack entry type: ` | Server can't decode this stack type | --- @@ -132,10 +132,10 @@ title: "API v2 error codes" Same stack/cell/slice validation as get methods (422), plus: -| Status | Error | Meaning | -|--------|-------|---------| -| 500 | `Exit code != 0` | Simulation failed | -| 500 | `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Unsupported address type | +| Status | Error | Meaning | +| ------ | -------------------------------------------------------------------------------------- | ------------------------ | +| 500 | `Exit code != 0` | Simulation failed | +| 500 | `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Unsupported address type | --- @@ -143,14 +143,14 @@ Same stack/cell/slice validation as get methods (422), plus: **Endpoint:** `/api/v2/getTokenData` -| Status | Error | Meaning | -|--------|-------|---------| -| 409 | `Smart contract
is not Jetton or NFT` | Contract doesn't implement Jetton/NFT interface | -| 500 | `Failed to unpack token data` | Couldn't decode metadata cell | -| 500 | `Invalid uri` / `missing uri field in offchain data` | Metadata URI is missing or malformed | -| 500 | `failed to serialize TokenData` | Internal serialization error | -| 500 | `Exit code != 0` | Get method failed | -| 500 | `Stack size < 5` | Not enough return values | +| Status | Error | Meaning | +| ------ | ---------------------------------------------------- | ----------------------------------------------- | +| 409 | `Smart contract
is not Jetton or NFT` | Contract doesn't implement Jetton/NFT interface | +| 500 | `Failed to unpack token data` | Couldn't decode metadata cell | +| 500 | `Invalid uri` / `missing uri field in offchain data` | Metadata URI is missing or malformed | +| 500 | `failed to serialize TokenData` | Internal serialization error | +| 500 | `Exit code != 0` | Get method failed | +| 500 | `Stack size < 5` | Not enough return values | --- @@ -158,11 +158,11 @@ Same stack/cell/slice validation as get methods (422), plus: **Endpoint:** `/api/v2/getConfigParam` -| Status | Error | Fix | -|--------|-------|-----| -| 422 | `failed to parse config_id` / `failed to parse param` | Not a valid integer | -| 422 | `only one of config_id or param should be specified` | Use one or the other, not both | -| 422 | `param should be non-negative` | Can't be negative | +| Status | Error | Fix | +| ------ | ----------------------------------------------------- | ------------------------------ | +| 422 | `failed to parse config_id` / `failed to parse param` | Not a valid integer | +| 422 | `only one of config_id or param should be specified` | Use one or the other, not both | +| 422 | `param should be non-negative` | Can't be negative | --- @@ -170,9 +170,9 @@ Same stack/cell/slice validation as get methods (422), plus: **Endpoint:** `/api/v2/getLibraries` -| Status | Error | Fix | -|--------|-------|-----| -| 422 | `failed to parse libraries` | Must be a valid JSON array of library IDs | +| Status | Error | Fix | +| ------ | --------------------------- | ----------------------------------------- | +| 422 | `failed to parse libraries` | Must be a valid JSON array of library IDs | --- @@ -180,6 +180,6 @@ Same stack/cell/slice validation as get methods (422), plus: **Endpoint:** `/api/v2/jsonRPC` -| Status | Error | Fix | -|--------|-------|-----| -| 422 | `params must contain an object` | `params` must be a single JSON object, not an array | +| Status | Error | Fix | +| ------ | ------------------------------- | --------------------------------------------------- | +| 422 | `params must contain an object` | `params` must be a single JSON object, not an array | From 475a57cec3455d3f6b73eca76238c0e4f2e2ff83 Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Fri, 28 Nov 2025 06:22:23 +0200 Subject: [PATCH 3/4] fix spelling --- ecosystem/api/toncenter/v2-errors.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem/api/toncenter/v2-errors.mdx b/ecosystem/api/toncenter/v2-errors.mdx index 7899feb8e..fbda70d78 100644 --- a/ecosystem/api/toncenter/v2-errors.mdx +++ b/ecosystem/api/toncenter/v2-errors.mdx @@ -27,7 +27,7 @@ title: "API v2 error codes" | ------ | -------------------------------- | ----------------------------------------------- | | 422 | `empty boc` | Include a non-empty `boc` field in request body | | 429 | `Ratelimit exceeded` | Back off and retry | -| 500 | `Exit code != 0` | Transaction simulation failed, check your BOC | +| 500 | `Exit code != 0` | Transaction simulation failed, check your BoC | | 504 | `LITE_SERVER_NETWORK timeout...` | Liteserver didn't respond in time, retry | --- From e91fe69c317e86884c62874ed9814bc0e0b3acac Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Mon, 1 Dec 2025 04:30:23 +0200 Subject: [PATCH 4/4] address ai comments --- ecosystem/api/toncenter/v2-errors.mdx | 124 +++++++++++--------------- 1 file changed, 52 insertions(+), 72 deletions(-) diff --git a/ecosystem/api/toncenter/v2-errors.mdx b/ecosystem/api/toncenter/v2-errors.mdx index fbda70d78..ae8bf52e4 100644 --- a/ecosystem/api/toncenter/v2-errors.mdx +++ b/ecosystem/api/toncenter/v2-errors.mdx @@ -6,16 +6,14 @@ title: "API v2 error codes" | Status | Meaning | | ------ | --------------------------------------------------- | -| 404 | Data not found | -| 405 | Wrong HTTP method (use GET or POST) | -| 409 | Resource exists but wrong type | -| 422 | Invalid request parameters | -| 429 | Rate limit exceeded | -| 500 | Server-side failure | -| 504 | Timeout waiting for liteserver | -| 542 | Liteserver-specific error or unsupported stack type | - ---- +| `404` | Data not found | +| `405` | Wrong HTTP method (use GET or POST) | +| `409` | Resource exists but wrong type | +| `422` | Invalid request parameters | +| `429` | Rate limit exceeded | +| `500` | Server-side failure | +| `504` | Timeout waiting for liteserver | +| `542` | Liteserver-specific error or unsupported stack type | ## By task @@ -25,12 +23,10 @@ title: "API v2 error codes" | Status | Error | Fix | | ------ | -------------------------------- | ----------------------------------------------- | -| 422 | `empty boc` | Include a non-empty `boc` field in request body | -| 429 | `Ratelimit exceeded` | Back off and retry | -| 500 | `Exit code != 0` | Transaction simulation failed, check your BoC | -| 504 | `LITE_SERVER_NETWORK timeout...` | Liteserver didn't respond in time, retry | - ---- +| `422` | `empty boc` | Include a non-empty `boc` field in request body | +| `429` | `Ratelimit exceeded` | Back off and retry | +| `500` | `Exit code != 0` | Transaction simulation failed, check the BoC | +| `504` | `LITE_SERVER_NETWORK timeout...` | Liteserver didn't respond in time, retry | ### Querying transactions @@ -38,17 +34,15 @@ title: "API v2 error codes" | Status | Error | Fix | | ------ | ----------------------------------------------------------------- | ------------------------------------------------------------- | -| 404 | `transaction not found` | No matching transaction exists for that source/destination/lt | -| 422 | `failed to parse address` | Address format is invalid | -| 422 | `failed to parse hash` | Hash format is invalid | -| 422 | `failed to parse lt` / `failed to parse created_lt` | Not a valid 64-bit integer | -| 422 | `lt should be non-negative` / `created_lt should be non-negative` | Value can't be negative | -| 422 | `lt and hash should be used together` | Provide both or neither | -| 422 | `empty source address` / `empty destination address` | Required parameter is missing | -| 422 | `limit should be positive` | Must be ≥ 1 | -| 422 | `limit should be less or equal 1000` | Max is 1000 | - ---- +| `404` | `transaction not found` | No matching transaction exists for that source/destination/lt | +| `422` | `failed to parse address` | Address format is invalid | +| `422` | `failed to parse hash` | Hash format is invalid | +| `422` | `failed to parse lt` / `failed to parse created_lt` | Not a valid 64-bit integer | +| `422` | `lt should be non-negative` / `created_lt should be non-negative` | Value can't be negative | +| `422` | `lt and hash should be used together` | Provide both or neither | +| `422` | `empty source address` / `empty destination address` | Required parameter is missing | +| `422` | `limit should be positive` | Must be ≥ 1 | +| `422` | `limit should be less or equal 1000` | Max is 1000 | ### Querying addresses & balances @@ -56,11 +50,9 @@ title: "API v2 error codes" | Status | Error | Fix | | ------ | -------------------------- | ------------------------------- | -| 422 | `empty address` | Include the `address` parameter | -| 422 | `failed to parse seqno` | Not a valid integer | -| 422 | `seqno should be positive` | Must be ≥ 1 | - ---- +| `422` | `empty address` | Include the `address` parameter | +| `422` | `failed to parse seqno` | Not a valid integer | +| `422` | `seqno should be positive` | Must be ≥ 1 | ### Querying blocks @@ -68,23 +60,21 @@ title: "API v2 error codes" | Status | Error | Fix | | ------ | --------------------------------------------------------------- | ----------------------------- | -| 422 | `workchain required` | Include `workchain` parameter | -| 422 | `shard required` | Include `shard` parameter | -| 422 | `seqno required` | Include `seqno` parameter | -| 422 | `failed to parse workchain` | Not a valid integer | -| 422 | `failed to parse shard` | Not a valid shard identifier | -| 422 | `failed to parse root_hash` | Not a valid 256-bit hash | -| 422 | `failed to parse seqno` | Not a valid integer | -| 422 | `seqno should be positive` | Must be ≥ 1 | -| 422 | `from_seqno should be non-negative` | Can't be negative | -| 422 | `exactly one of seqno, lt, unixtime should be specified` | Provide exactly one selector | -| 422 | `lt should be non-negative` / `unixtime should be non-negative` | Can't be negative | -| 422 | `after_lt and after_hash should be used together` | Provide both or neither | -| 422 | `after_lt should be non-negative` | Can't be negative | -| 422 | `count should be positive` | Must be ≥ 1 | -| 422 | `count should be less or equal 10000` | Max is 10,000 | - ---- +| `422` | `workchain required` | Include `workchain` parameter | +| `422` | `shard required` | Include `shard` parameter | +| `422` | `seqno required` | Include `seqno` parameter | +| `422` | `failed to parse workchain` | Not a valid integer | +| `422` | `failed to parse shard` | Not a valid shard identifier | +| `422` | `failed to parse root_hash` | Not a valid 256-bit hash | +| `422` | `failed to parse seqno` | Not a valid integer | +| `422` | `seqno should be positive` | Must be ≥ 1 | +| `422` | `from_seqno should be non-negative` | Can't be negative | +| `422` | `exactly one of seqno, lt, unixtime should be specified` | Provide exactly one selector | +| `422` | `lt should be non-negative` / `unixtime should be non-negative` | Can't be negative | +| `422` | `after_lt and after_hash should be used together` | Provide both or neither | +| `422` | `after_lt should be non-negative` | Can't be negative | +| `422` | `count should be positive` | Must be ≥ 1 | +| `422` | `count should be less or equal 10000` | Max is 10,000 | ### Running get methods @@ -124,8 +114,6 @@ title: "API v2 error codes" | -------------------------------------- | ----------------------------------- | | `Unsupported stack entry type: ` | Server can't decode this stack type | ---- - ### Estimating fees **Endpoint:** `/api/v2/estimateFee` @@ -134,10 +122,8 @@ Same stack/cell/slice validation as get methods (422), plus: | Status | Error | Meaning | | ------ | -------------------------------------------------------------------------------------- | ------------------------ | -| 500 | `Exit code != 0` | Simulation failed | -| 500 | `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Unsupported address type | - ---- +| `500` | `Exit code != 0` | Simulation failed | +| `500` | `addr_ext is not supported` / `addr_var is not supported` / `anycast is not supported` | Unsupported address type | ### Token & NFT data @@ -145,14 +131,12 @@ Same stack/cell/slice validation as get methods (422), plus: | Status | Error | Meaning | | ------ | ---------------------------------------------------- | ----------------------------------------------- | -| 409 | `Smart contract
is not Jetton or NFT` | Contract doesn't implement Jetton/NFT interface | -| 500 | `Failed to unpack token data` | Couldn't decode metadata cell | -| 500 | `Invalid uri` / `missing uri field in offchain data` | Metadata URI is missing or malformed | -| 500 | `failed to serialize TokenData` | Internal serialization error | -| 500 | `Exit code != 0` | Get method failed | -| 500 | `Stack size < 5` | Not enough return values | - ---- +| `409` | `Smart contract
is not Jetton or NFT` | Contract doesn't implement Jetton/NFT interface | +| `500` | `Failed to unpack token data` | Couldn't decode metadata cell | +| `500` | `Invalid uri` / `missing uri field in offchain data` | Metadata URI is missing or malformed | +| `500` | `failed to serialize TokenData` | Internal serialization error | +| `500` | `Exit code != 0` | Get method failed | +| `500` | `Stack size < 5` | Not enough return values | ### Config parameters @@ -160,11 +144,9 @@ Same stack/cell/slice validation as get methods (422), plus: | Status | Error | Fix | | ------ | ----------------------------------------------------- | ------------------------------ | -| 422 | `failed to parse config_id` / `failed to parse param` | Not a valid integer | -| 422 | `only one of config_id or param should be specified` | Use one or the other, not both | -| 422 | `param should be non-negative` | Can't be negative | - ---- +| `422` | `failed to parse config_id` / `failed to parse param` | Not a valid integer | +| `422` | `only one of config_id or param should be specified` | Use one or the other, not both | +| `422` | `param should be non-negative` | Can't be negative | ### Libraries @@ -172,9 +154,7 @@ Same stack/cell/slice validation as get methods (422), plus: | Status | Error | Fix | | ------ | --------------------------- | ----------------------------------------- | -| 422 | `failed to parse libraries` | Must be a valid JSON array of library IDs | - ---- +| `422` | `failed to parse libraries` | Must be a valid JSON array of library IDs | ### JSON-RPC @@ -182,4 +162,4 @@ Same stack/cell/slice validation as get methods (422), plus: | Status | Error | Fix | | ------ | ------------------------------- | --------------------------------------------------- | -| 422 | `params must contain an object` | `params` must be a single JSON object, not an array | +| `422` | `params must contain an object` | `params` must be a single JSON object, not an array |