EIP RPC errors

[bas-vk]

Problem

The RPC specification implements a subset of the JSON-RPC specification. It defines the available RPC methods together with in- and outputs and serialisation format. It however doesn't specify anything about the errors these methods can return. As a result implementations return different errors which makes it hard for DApp developers to act appropriately. Another problem is that currently there are no well defined errors codes. This causes some clients (e.g. Mist) to do string matching to determine what happened. This is brittle and not generic.

Proposal

Define a standard for Ethereum JSON-RPC errors. One of the problems is finding the correct balans between informing a DApp what happend and being not too specific. Being too specific will make it hard to become fully complient with the specification and would make DApp's more complicated. Being too generic DApps' won't be able to determine what happened.

This problem is tackled by introducing the concept of an error category and allow a node to supply optional extra information about an error. This allows a DApp to get a general understanding what went wrong by looking at the category error code. It also allow a node to provide additional information about an error which the DApp can decide to use.

This proposal contains 2 parts. First it describes how the errors are defined. The second part describes a list with standardized error categories and detailed error messages.

Error structure

JSON-RPC 2.0 has a section dedicated how errors are defined. The code field will be used for an error category. This field is mandatory and used by DApp's to get a general understanding what happend. Together with the code field the message field is filled with a brief description about the category. See for more information about available categories and their description the next section.

The data field is an optional field. Nodes can decide to supply additonal information through this field. If a node provides detailed information the data field must be an array of objects with the following fields:

field	type	mandatory
code	integer	yes
description	string	no

By using this approach DApp's can get a general understanding what happend through the code field. In most cases this is sufficient. It also allow nodes to supply additional information when available.

Error categories

The JSON-RPC 2.0 specification defines the range -32000 to -32099 for application specific errors.

code	category	meaning
-32000	INVALID_VALUE	parameter contains invalid value
-32001	NOT_FOUND	requested resource not found
-32002	UNAVAILABLE	resource not available
-32003	TX_REJECTED	transaction rejected
-32099	MISC	error, allow nodes to send custom errors

Error details

If a node wants to send additional information about an error it can use the data field.

category	code	meaning
INVALID_VALUE	0	invalid input, e.g. missing mandatory input
TX_REJECTED	0	invalid nonce
TX_REJECTED	1	unable to sign transaction
TX_REJECTED	2	transaction already in tx pool
TX_REJECTED	3	transaction gas price too low for acceptance
TX_REJECTED	4	sender account doesn't exists
TX_REJECTED	5	gas limit exceeds block gas limit
TX_REJECTED	6	insufficient funds
TX_REJECTED	7	insufficient intrinsic gas
TX_REJECTED	8	from account is locked
*	99	implementation specific field

It is worth noting that 99 is a general code that can be used in any of the categories. It allows a node to provide non-standarised information to a DApp. Also this table doesn't specify the description field. Nodes are free to choose what they put into the description field, it is allowed to omit the description field.

Example

Value transaction from an account with a balance of 0. The node determines this transaction will always fail and rejects the transaction. The returned error would look like:

{"jsonrpc": "2.0", "error": {"code": -32003, "message": "transaction rejected", "data":[{"code": 6, "description": "insufficient funds"}]}, "id": 1234}

The node doesn't uses the account management most implementations provides but forwards a transaction to an external signing service. When this service could not be reached the node can return the following error:

{"jsonrpc": "2.0", "error": {"code": -32003, "message": "transaction rejected", "data":[{"code": 1, "description": "unable to sign transaction"},{"code": 99, "description": "signing service not available"}]}, "id": null}

Required changes

• the rpc-test suite needs to be updated
• implementations must be updated

[danfinlay]

I love this, and think it will make error handling much easier for developers.

I'd also like to see a tx_rejected error code for when the user rejects the transaction.

On Jul 25, 2016, at 4:48 AM, bas-vk notifications@github.com wrote:

Problem

The RPC specification implements a subset of the JSON-RPC specification. It defines the available RPC methods together with in- and outputs and serialisation format. It however doesn't specify anything about the errors these methods can return. As a result implementations return different errors which makes it hard for DApp developers to act appropriately. Another problem is that currently there are no well defined errors codes. This causes some clients (e.g. Mist) to do string matching to determine what happened. This is brittle and not generic.

Proposal

Define a standard for Ethereum JSON-RPC errors. One of the problems is finding the correct balans between informing a DApp what happend and being not too specific. Being too specific will make it hard to become fully complient with the specification and would make DApp's more complicated. Being too generic DApps' won't be able to determine what happened.

This problem is tackled by introducing the concept of an error category and allow a node to supply optional extra information about an error. This allows a DApp to get a general understanding what went wrong by looking at the category error code. It also allow a node to provide additional information about an error which the DApp can decide to use.

This proposal contains 2 parts. First it describes how the errors are defined. The second part describes a list with standardized error categories and detailed error messages.

Error structure

JSON-RPC 2.0 has a section dedicated how errors are defined. The code field will be used for an error category. This field is mandatory and used by DApp's to get a general understanding what happend. Together with the code field the message field is filled with a brief description about the category. See for more information about available categories and their description the next section.

The data field is an optional field. Nodes can decide to supply additonal information through this field. If a node provides detailed information the data field must be an array of objects with the following fields:

field type mandatory
code integer yes
description string no
By using this approach DApp's can get a general understanding what happend through the code field. In most cases this is sufficient. It also allow nodes to supply additional information when available.

Error categories

The JSON-RPC 2.0 specification defines the range -32000 to -32099 for application specific errors.

code description meaning
-32000 INVALID_VALUE parameter contains invalid value
-32001 NOT_FOUND requested resource not found
-32002 UNAVAILABLE resource not available
-32003 TX_REJECTED transaction rejected
-32099 MISC error, allow nodes to send custom errors
Error details

If a node wants to send additional information about an error it can use the data field.

category code meaning
INVALID_VALUE 0 invalid input, e.g. missing mandatory input
TX_REJECTED 0 invalid nonce
TX_REJECTED 1 unable to sign transaction
TX_REJECTED 2 transaction already in tx pool
TX_REJECTED 3 transaction gas price too low for acceptance
TX_REJECTED 4 sender account doesn't exists
TX_REJECTED 5 gas limit exceeds block gas limit
TX_REJECTED 6 insufficient funds
TX_REJECTED 7 insufficient intrinsic gas
TX_REJECTED 8 from account is locked

• 99 implementation specific field
  It is worth noting that 99 is a general code that can be used in any of the categories. It allows a node to provide non-standarised information to a DApp. Also this table doesn't specify the description field. Nodes are free to choose what they put into the description field, it is allowed to omit the description field.

Example

Value transaction from an account with a balance of 0. The node determines this transaction will always fail and rejects the transaction. The returned error would look like:

{"jsonrpc": "2.0", "error": {"code": -32003, "message": "transaction rejected", "data":[{"code": 6, "description": "insufficient funds"}]}, "id": 1234}
The node doesn't uses the account management most implementations provides but forwards a transaction to an external signing service. When this service could not be reached the node can return the following error:

{"jsonrpc": "2.0", "error": {"code": -32003, "message": "transaction rejected", "data":[{"code": 1, "description": "unable to sign transaction"},{"code": 99, "description": "signing service not available"}]}, "id": null}
Required changes

the rpc-test suite needs to be updated
implementations must be updated
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[fjl]

The JSON-RPC 2.0 specification defines the range -32000 to -32099 for application specific errors.

This is not entirely correct. The -32000..-32099 range is meant to be used for server errors, i.e. RPC protocol violations that are not covered by the spec. Codes from this range could be used for "invalid hex" and similar errors. Application errors can use any error code, positive numbers are acceptable too.

Since the available integer range is so big, it would be much simpler to ignore categories and define a separate error code number for each specific condition, e.g. (100: invalid transaction nonce, 101: unable to sign transaction, 102: insufficient funds, 103: gas price too low, 104: no such account, ...).
If a category is desired, you can use the magnitude of the number (e.g. 100..199: transaction rejected)
to indicate it.

One important question is the definitive list of errors that must be detected by every compliant implementation of the web3 API. The list you have covers errors for eth_sendTransaction. Are there any other errors that should be included for the initial version of this spec?

[tymat]

I would like to add "Unsupported" error code which would be a good way for Metamask style sub-providers to tell the client to use a different provider. Not sure if NOT FOUND can be used in this instance...

[flexsingit]

Can anyone let me know that what is the meaning of Error: known transaction ?Please

[RobertoC27]

can anyone tell how far along is this? or this has already been implemented, thanks!

[MicahZoltu]

I haven't really thought through this yet, but in my experience there is value in classifying errors broadly into "retriable" or not. That is, is it possible that if the app were to try again that the transaction will succeed or will the transaction definitely not succeed no matter how many times it is tried.

User rejected or gas too low, for example, is a retryable error while a malformed transaction is a non-retryable error.

[bitpshr]

Hi @bas-vk. Do you plan to formalize this proposal into an EIP and submit a pull request?

[frozeman]

I think @bas-Vlad is not very active anymore. Somebody needs to overtake that.

[bitpshr]

Thanks @frozeman. I'm finishing an EIP to formalize the current RPC specification so it doesn't only exist in a wiki. I'll either roll this error handling into that RPC EIP, or submit this as a separate EIP soon after.