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.

CodeMeaningMessage (Example)Notes


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

Last updated