Skip to content

API v2 error codes #1470

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+166 −0
Open

API v2 error codes #1470

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
abe0e08
API v2 error codes
laviniat1996 Nov 28, 2025
428b49c
fix linting
laviniat1996 Nov 28, 2025
ca7e814
Merge branch 'main' into v2-errors
laviniat1996 Nov 28, 2025
475a57c
fix spelling
laviniat1996 Nov 28, 2025
e91fe69
address ai comments
laviniat1996 Dec 1, 2025
5f364bb
Merge branch 'main' into v2-errors
laviniat1996 Dec 1, 2025
6859e35
Merge branch 'main' into v2-errors
laviniat1996 Dec 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@
"expanded": true,
"pages": [
"ecosystem/api/toncenter/get-api-key",
"ecosystem/api/toncenter/v2-errors",
{
"group": "API v2",
"openapi": {
Expand Down
165 changes: 165 additions & 0 deletions ecosystem/api/toncenter/v2-errors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <N> != 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 |
Comment on lines +24 to +45
Copy link

@github-actions github-actions bot Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[HIGH] Error messages use code spans instead of quotation marks

In the API v2 error tables, literal error strings (for example, empty boc, transaction not found, and related messages in the “Error” column) are formatted as inline code spans instead of being wrapped in quotation marks. The style guide explicitly requires log messages and error strings to appear verbatim in quotation marks and marks this as a HIGH-severity rule, while reserving code formatting for error codes/identifiers (see https://github.com/ton-org/docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L276-L295). Presenting these messages as code spans makes it harder to grep for exact strings and diverges from the mandated quoting convention. The same pattern repeats across the other error tables in this file and should be normalized consistently.

Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!


### 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 <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 <N> != 0` | Get method returned non-zero exit code |
| `Stack size <N> < 5` | Contract returned fewer values than expected |
| `Failed to parse int: <value>` | Couldn't parse numeric result |
| `stackEntryNumber expected` / `stackEntryNumber expected at 0 position` | Expected number, got something else |
| `stackEntryCell expected at <N> 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: <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 <N> != 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 <address> 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 <N> != 0` | Get method failed |
| `500` | `Stack size <N> < 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 |