API v2 error codes #1470
API v2 error codes #1470
Conversation
This comment was marked as resolved.
This comment was marked as resolved.
laviniat1996
force-pushed
the
v2-errors
branch
from
4c0e360 to
428b49c
Compare
verytactical
added
the
3p
|
Please ping when it's ready for final editing. |
|
/review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| | 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 | |
There was a problem hiding this comment.
[HIGH] HTTP status codes not formatted as code literals
In the overview table, HTTP status codes such as 404, 405, 422, 429, 500, 504, and 542 are rendered as plain text instead of code literals. The extended style guide requires code, paths, and other literal values that developers copy or compare programmatically to use code formatting, and HTTP status codes fall into this category. Leaving them unformatted makes it harder to visually distinguish code-like tokens and is inconsistent with other parts of the documentation. Similar unformatted status codes appear in other tables in this file and should be updated consistently.
| | 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 | |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| | 504 | Timeout waiting for liteserver | | ||
| | 542 | Liteserver-specific error or unsupported stack type | | ||
|
|
||
| --- |
There was a problem hiding this comment.
[HIGH] Horizontal rules used instead of headings/whitespace
The file uses a Markdown thematic break (---) in the content body at line 18, in addition to the frontmatter delimiters at lines 1 and 3. The style guide restricts --- to YAML frontmatter and requires using headings, whitespace, or components such as <Aside> to separate sections. Similar separators appear later in the file (for example around the task sections), so the current pattern encourages further misuse of horizontal rules. This makes the document structure less consistent with the rest of the docs and harder to maintain.
| --- |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| | 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 your BoC | | ||
| | 504 | `LITE_SERVER_NETWORK timeout...` | Liteserver didn't respond in time, retry | |
There was a problem hiding this comment.
[HIGH] Error messages use code font instead of quotation marks
In the “Sending transactions” table, literal error message strings such as empty boc, Ratelimit exceeded, Exit code <N> != 0, and LITE_SERVER_NETWORK timeout... are formatted as code spans in the Error column. The style guide’s rule for quotation marks and error strings requires verbatim log and error messages to be presented in quotation marks, not as code, to match how they appear in logs and improve grep-ability. Using code styling here blurs the distinction between log text and actual code or parameter names. The same pattern of backtick-formatted error strings recurs throughout the other error tables in this file and should be corrected consistently.
| | 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 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 <N> != 0" | Transaction simulation failed, check your BoC | | |
| | 504 | "LITE_SERVER_NETWORK timeout..." | Liteserver didn't respond in time, retry | |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Error messages should stay in code font
| | ------ | -------------------------------- | ----------------------------------------------- | | ||
| | 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 your BoC | |
There was a problem hiding this comment.
[HIGH] Second‑person pronoun “your” addressing the reader
The Fix text for the Exit code <N> != 0 row in the “Sending transactions” table says “Transaction simulation failed, check your BoC” at line 30. The documentation style guide bans second‑person pronouns such as “you” and “your” in order to keep tone neutral and impersonal. Leaving this phrasing in place makes the entry inconsistent with the rest of the documentation and violates the pronoun rules.
| | 500 | `Exit code <N> != 0` | Transaction simulation failed, check your BoC | | |
| | 500 | `Exit code <N> != 0` | Transaction simulation failed, check the BoC | |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| | 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 | |
There was a problem hiding this comment.
[HIGH] Error strings formatted as code instead of quoted log messages
Literal API error messages in the tables are formatted as inline code spans (wrapped in backticks) instead of as quoted strings. For example, in the “Querying transactions” table at lines 41–49, messages such as transaction not found, failed to parse address, and lt should be non-negative are shown in code font rather than in double quotation marks. The style guide requires log and error messages to be presented verbatim in quotes so they are clearly recognizable as returned text and easy to copy. The same pattern appears earlier in the file (for example empty boc, Ratelimit exceeded) and should be updated consistently.
| | 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 | |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
There was a problem hiding this comment.
Error messages should stay in code font
| | 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 | |
There was a problem hiding this comment.
[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!
closes #1022
This doc adds all error codes I could find in the codebase for API v2.