JSON RPC Error codes standardization: open-rpc extension specs [A Sample implementation]

[simsonraj]

Goal

A standard for JSON-RPC error codes and messages across EVM-compatible chains and execution clients to improve interoperability, facilitate consistent error handling, and provide a better developer experience.

Motivation

Different Ethereum clients and EVM-compatible chains often use overlapping error codes or generic messages in their JSON-RPC API responses. This inconsistency confuses end users and developers, complicates cross-client tooling, and hampers interoperability.

Solution Abstract

• This is made possible by extending the Open-RPC spec to support Extension specs, particularly by utilizing the x-error-group extension spec

• This solution aims to address the inconsistent error codes by categorising common error scenarios

• Each category could have a reserved range (200 in this case) error codes allotted between (-31999 to -30000), excluding the ranges specified in the JSON-RPC 2.0 specification.

• Example: Below is an example categorisation to imagine how the standardization could look like & can be amended as per feedback with different stakeholders

  • Standard JSON-RPC Errors (-32768 to -32000) (existing)
  • Client-specific Errors (-32099 to -32000) (existing)
  • Gas/Fees Errors (-31999 to -31800)
  • EVM-related Errors (-31799 to -31600)
  • Consensus Errors (-31599 to -31400)
  • Network Errors (-31399 to -31200)
  • TxPool Errors (-31199 to -31000)

• Expected Error codes response validation implementation can be found here