diff --git a/docs.json b/docs.json index 8306c1d2f..571cf8143 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..ae8bf52e4 --- /dev/null +++ b/ecosystem/api/toncenter/v2-errors.mdx @@ -0,0 +1,165 @@ +--- +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 the 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 |