The format of an error message that the RPC returns:
"jsonrpc": "2.0",
"error": {
"code": -32602,
"message": "Layer1Address deserialize error: incorrect Layer1Address format"
"id": 1
  • code: error code
  • message: error message in English

Error Types

  • -32602: incorrect number of parameters or unable to serialize parameters correctly
  • 100-200: parameter value is not within the correct range
  • 201-300: Incorrect state, such as insufficient account balance for a transfer
  • 500: RPC server internal error

Error Code

The table below lists most error codes and their meanings. While the error codes and meanings generally remain the same, the error messages may change with version iterations. The range from -32768 to -32000 represents the predefined errors in the JSON RPC 2.0 protocol and are less likely to occur if the API documentation is followed. The range from 100 to 500 represents custom errors defined by the zklink RPC server and should be handled by the caller.
Message (Example)
Incorrect number of parameters or the parameters cannot be serialized correctly.
Layer1Address deserialize error: incorrect Layer1Address format
This error can occur if the RPC is not called following the API documentation.
Invalid chain ID
Invalid chain id
Related to the chains that zklink connects. For example, if there are 4 supported chains, the correct range for chain IDs would be [1, 4].
Invalid account ID
Invalid account id
[0, 2^24 -1]
Invalid subaccount ID
Invalid sub account id
[0, 7]
Invalid token ID
Invalid token id
[1, 65535]
Invalid block range
Invalid block range
blockEnd >= blockStart
Invalid transaction type
Invalid tx type
Only specific transaction types are supported for querying transaction history or submitting transactions. Refer to API doc for details.
Invalid field in a format
Invalid tx format
There can be various reasons for this error, such as an incorrect transfer accountId or inconsistent subAccountIds between maker and taker in OrderMatching. Refer to API doc for details.
Invalid ChangePubKey auth type
Invalid change pubkey auth type
Only Onchain, EthECDSA, and EthCREATE2 are currently supported.
Fail to pass ChangePubKey auth check
Invalid change pubkey auth data
Refer to zkLink API doc.
Missing or invalid layer1 signature
Missing or invalid layer one signature
All Layer3 transactions, except ChangePubKey, require a valid Layer 1 signature.
Invalid Layer 2 signature
Invalid zk signature
All Layer 2 transactions require a valid Layer 2 signature.
Missing submitter's Layer 2 signature
Missing or invalid submitter zk signature
When a transaction results in the asset decrease in subaccounts (except #0 subaccount), a valid submitter signature must be provided.
Invalid taker's Layer 2 signature
Invalid taker zk signature
Invalid maker's Layer 2 signature
Invalid maker zk signature
Account not found
Account not found
The account does not exist in the state tree.
Token configuration not found
Token not found
The token configuration does not exist in the state tree.
Tx not found
Tx not found
Cannot find the transaction record in the database.
The account not actived
Account not active
The account needs to be activated before executing Layer 2 transactions (except for ChangePubKey).
Incorrect nonce
Incorrect nonce
The transaction nonce must be monotonically increasing.
Insufficient account balance
Insufficient account balance
When involving a decrease in account assets, the account balance is checked for sufficiency.
The fee for the transaction is too low
Fee too low
All Layer 2 transactions require a fee, which can be obtained through get_tx_fee.
The withdraw amount exceeds available contract reserve
Withdraw amount exceed contract reserve
The Withdraw or ForcedExit transaction checks the withdrawal amount. The token_remain API can be used to query the reserve on Layer1 contract.
ForcedExit transaction cannot be initiated to activated account
Can not force exit active account
ForcedExit can only be iniciated to accounts that haven't been activated.
Target account of ForcedExit exists less than required minimum time
Target account exists less than required minimum time
When initiating a ForcedExit transaction to an inactive account, the account must exist for a certain duration, such as 24 hours, to provide enough time for the account to be activated.
Target account address of ForcedExit is 0xffffffffffffffffffffffffffffffffffffffff
Target account can not be global asset account
The address 0xffffffffffffffffffffffffffffffffffffffff is a global asset account, and ForcedExit is not allowed on this account.
Submitter is not in the whitelist
Submitter not in whitelist
A submitter's signature is required when a transaction results in a decrease of assets in a subaccount (except #0 subaccount). The submitter needs to be registered on zkLink.
A transaction is submitted for more than once
Duplicate tx
The submitted transaction hash must be unique and should not be duplicated.
Block not found
Block not found
The block height exceeds the latest block height.
The initicator forced_exit it's own account
Initiator account cannot be the target account, please Withdraw transaction
When the initiator is attempting to force withdraw its own assets, it should initiate a withdraw transaction.
Server internal error
Server internal error

Notable Errors


When using some APIs that involve querying account status such as getAccount, getAccountSnapshot, etc., if the account does not exist, it will return this error message, rather than returning a default. This is because the account with 'accountId=0' is a Layer3 fee account, and the default accountId is also 0. If the account does not exist, returning the default value will cause confusion.


Transaction fees are related to Layer3 token price, which is stable over a period of time (for example, half an hour). If the price is updated just after get_tx_fee, tx_submit may fail. In this case, the initiator need to re-query the transaction fee and then try to submit the transaction again.\
version: 7df6cd1