JSON-RPC Errors
The format of an error message that the RPC returns:
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
Last updated