[Ethereum] Is JSON-RPC error behavior documented

go-ethereumjson-rpc

Running geth, it's easy to see what its implementation of JSON-RPC does on errors:

$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSolidity","params":["contract test { function multiply(uint a) returns(uint d) {   rxturn a * 7;   } }"],"id":1}' http://localhost:8545
{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"solc: exit status 1\n\u003cstdin\u003e:1:72: Error: Expected token Semicolon got 'Mul'\ncontract test { function multiply(uint a) returns(uint d) {   rxturn a * 7;   } }\n                                                                       ^\n"}}

$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "lxtest"],"id":1}' http://localhost:8545
{"jsonrpc":"2.0","id":1,"error":{"code":-32602,"message":"invalid blocknumber \"lxtest\""}}

$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "latest"]}' http://localhost:8545
{"jsonrpc":"2.0","error":{"code":-32700,"message":"missing request id"}}

We get a JSON response containing an error object rather than the expected output, where error includes an integer code and a descriptive message.

But (am I blind?) I can't seem to documentation of this behavior in the spec, or any information on the codes.

Is error behavior in JSON-RPC standard across implementations? Can one safely rely on the code/message response format, even if the codes have not been fully worked out?

Thanks, and apologies if, not unusually, I'm just not looking in obvious right places.

Best Answer

Geth uses JSON-RPC 2.0 spec and so it maps error codes specified there (see errors.go and bridge.go for example). You can relay on those error code/messages, and in particular you can relay on the following specifications:

5.1 Error object

When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members:

code: Number that indicates the error type that occurred. This MUST be an integer.

message: String providing a short description of the error. The message SHOULD be limited to a concise single sentence.

data: Primitive or Structured value that contains additional information about the error. This may be omitted. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).

The error codes from and including -32768 to -32000 are reserved for pre-defined errors. Any code within this range, but not defined explicitly below is reserved for future use. The error codes are nearly the same as those suggested for XML-RPC at the following url: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

-32700 -- Parse error -- Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

-32600 -- Invalid Request -- The JSON sent is not a valid Request object.

-32601 -- Method not found -- The method does not exist / is not available.

-32602 -- Invalid params -- Invalid method parameter(s).

-32603 -- Internal error -- Internal JSON-RPC error.

-32000 to -32099 -- Server error -- Reserved for implementation-defined server-errors.

The remainder of the space is available for application defined errors.

Related Topic