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

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