Links

JSON-RPC Errors

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.
Code
Meaning
Message (Example)
Notes
-32602
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.
100
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].
101
Invalid account ID
Invalid account id
[0, 2^24 -1]
102
Invalid subaccount ID
Invalid sub account id
[0, 7]
103
Invalid token ID
Invalid token id
[1, 65535]
104
Invalid block range
Invalid block range
blockEnd >= blockStart
105
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.
106
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.
107
Invalid ChangePubKey auth type
Invalid change pubkey auth type
Only Onchain, EthECDSA, and EthCREATE2 are currently supported.
108
Fail to pass ChangePubKey auth check
Invalid change pubkey auth data
Refer to zkLink API doc.
109
Missing or invalid layer1 signature
Missing or invalid layer one signature
All Layer3 transactions, except ChangePubKey, require a valid Layer 1 signature.
110
Invalid Layer 2 signature
Invalid zk signature
All Layer 2 transactions require a valid Layer 2 signature.
111
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.
112
Invalid taker's Layer 2 signature
Invalid taker zk signature
-
113
Invalid maker's Layer 2 signature
Invalid maker zk signature
-
201
Account not found
Account not found
The account does not exist in the state tree.
202
Token configuration not found
Token not found
The token configuration does not exist in the state tree.
203
Tx not found
Tx not found
Cannot find the transaction record in the database.
204
The account not actived
Account not active
The account needs to be activated before executing Layer 2 transactions (except for ChangePubKey).
205
Incorrect nonce
Incorrect nonce
The transaction nonce must be monotonically increasing.
206
Insufficient account balance
Insufficient account balance
When involving a decrease in account assets, the account balance is checked for sufficiency.
207
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.
208
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.
209
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.
210
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.
211
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.
212
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.
213
A transaction is submitted for more than once
Duplicate tx
The submitted transaction hash must be unique and should not be duplicated.
214
Block not found
Block not found
The block height exceeds the latest block height.
215
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.
500
Server internal error
Server internal error

Notable Errors

201

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.

207

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