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