FRC-0116: JSON-RPC HTTP conventions

[LesnyRumcajs]

Proposal on unifying the HTTP response code conventions with the JSON-RPC API.

Discussions thread

[jennijuju]

editorial review ✅ (v well written!

[rvagg]

I should have commented in the discussion so I moved my text there: #1247 (comment)

original comment

I introduced -32005 in filecoin-project/lotus#13561, with the intention of trying to align more with the Ethereum ecosystem on jsonrpc patterns, at least for our Ethereum calls. In this case, it aligns with EIP-1474. Unfortunately this is not a uniformly adopted EIP so Ethereum RPC providers are all over the place with this. But if you look at the codes described there they are not all application logic problems and don't belong as 500s. Currently the majority of error codes Lotus returns are going to be 200's, and I'd read that as "valid json in response, deal with it". A quick survey of the various public Ethereum nodes show that a "range exceeded", while not universally -32005, are universally http 200 responses (e.g. Cloudflare, PublicNode, 1RPC, and Merkle all return HTTP 200 for block range exceeded errors), parse errors are the one place where some providers return 400. From what I can tell, 200-for-everything is Ethereum standard. My 2c is that I'd be happy with mostly 200, maybe some 500's for some "something went badly wrong" and 4xx's for "not here" type errors.

One challenge for Go is that the go-jsonrpc client rejects non-200/400/500 responses entirely, not even parsing the body, it doesn't even accept them as expected & valid. So we'd have to introduce a change there and cross our fingers that every Go consumer application (mainly miner software) updates to that before we go about introducing new error codes.

How about 200 for all handler/application errors (matching Ethereum ecosystem practice), 400 for malformed requests (-32700, -32600, -32602), and 500 only for genuine server failures (-32603)?

[jsoares]

The goal is standardising response codes across implementations is a valuable one. People can disagree on the ideal standard, but this proposal is well-drafted and internally consistent, so 👍 on advancing.

[jsoares]

The FRC already has a number and two approving reviews. While the process for FRCs has always been a bit more malleable, I'm fine with merging if no forthcoming changes.

cc @rvagg given previous thoughts expressed in discussion