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.

  • so, earlier today i thought there was an answer pointing out that ethereum's json-rpc spec is in fact a specialization of this json-rpc spec, which does indeed document in broad terms both the success and error formats that geth uses (although necessarily not all of the specific error codes). i had wanted to log in tonight to mark that answer correct, because i think it is, but alas the answer seems to have been deleted. Jun 5, 2016 at 9:00
  • I thought you're asking if Geth and all compliant clients will return identical error messages; since errors aren't specified in Ethereum's JSON-RPC spec I think no assurances can be currently provided about any consistency across clients regarding errors.
    – eth
    Jun 16, 2016 at 9:47
  • thanks! that seems right, given the generality of the base specification. it might be nice, someday, for at least some common errors to have specified messages and codes, but for now that's probably not something to rely upon... Jun 17, 2016 at 10:17

2 Answers 2


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.


If you are in the USA, you will get error code 32602 if you try to swap or trade on your ledger. You need a VPN, with a foreign IP to use these functions.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.