# DApp Error Support

See the Error Encoding Guide for example codes

## Motivation​

The RPC specification implements a subset of the JSON-RPC specification. It defines the available RPC methods together with in- and outputs and serialization 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 error codes. This causes some clients (e.g. Mist) to do string matching to determine what happened. This is brittle and not generic.

## DApp Error Support​

### Define a standard for Ethereum JSON-RPC errors.​

One of the problems is finding the correct balance between informing a DApp what happened and being not too specific. Being too specific will make it hard to become fully compliant 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 allowing a node to supply optional extra information about an error. This allows a DApp to get a general understanding of what went wrong by looking at the category error code. It also allows a node to provide additional information about an error that 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 of what happened. Together with the code field, the message` field is filled with a brief description of the category.

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

FieldTypeMandatory
CodeIntegerYes
DescriptionStringNo

By using this approach DApp's can get a general understanding of what happened through the code field. In most cases this is sufficient. It also allows 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.

CodeCategoryMeaning
-32000INVALID_VALUEParameter Contains Invalid Value
-32002UNAVAILABLEResource Not Available
-32003TX_REJECTEDTransaction Rejected
-32099MISCError, 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.

CodeCategoryMeaning
0INVALID_VALUEInvalid Input, E.g. Missing Mandatory Input
0TX_REJECTEDInvalid Nonce
1TX_REJECTEDUnable To Sign Transaction
3TX_REJECTEDTransaction Gas Price Too Low For Acceptance
4TX_REJECTEDSender Account Doesn'T Exists
5TX_REJECTEDGas Limit Exceeds Block Gas Limit
6TX_REJECTEDInsufficient Funds
7TX_REJECTEDInsufficient Intrinsic Gas
8TX_REJECTEDFrom 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-standardized 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 this:

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

The node doesn't use the account management most implementations provide 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
}