JSON RPC Error codes standardization using open-rpc extension specs #650

simsonraj · 2025-05-10T15:42:09Z

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

Reserved ranges at a glance

Extension group	Category label	Reserved range	Source
JSON-RPC standard	—	$-32768$ to $-32000$	JSON-RPC 2.0 spec
JSON-RPC non-standard	Client-specific	$-32099$ to $-32000$	JSON-RPC 2.0 addendum
Gas errors	`GAS_ERRORS`	$800$ to $999$	`gas-error-groups.yaml`
Execution errors	`EXECUTION_ERRORS`	$1$ to $199$	`execution-errors.yaml`
TxPool errors	`TXPOOL_ERRORS`	$1000$ to $1199$	`txpool-errors.yaml`
ZK execution errors	`ZK_EXECUTION_ERRORS`	$2000$ to $2199$	`zk-execution-errors.yaml`

Expected Error codes response validation implementation can be found here
Error test suite for different clients https://github.com/simsonraj/eth-err-tests

Error groups - Extended open-rpc spec sample implementation

scripts/build.js

Co-authored-by: Zane Starr <zcstarr@gmail.com>

sambacha · 2025-05-28T06:44:10Z

STOP THIS A.I. SLOP NOW!!!!!!!!!!!!

zcstarr · 2025-05-28T14:37:46Z

@sambacha this is not AI, but the culmination of many months and pretty close to a year of work, to put together a PR that can help move the ecosystem forward. If you have a criticism of the PR or something about it's content please feel free to comment with something constructive or instructive.

If you don't have anything constructive to add to this conversation, please refrain from spamming the PR with comments

meta data extension

Co-authored-by: Zane Starr <zcstarr@gmail.com>

Sync main again

zcstarr · 2025-09-29T14:48:15Z

scripts/build.js

+let extensionSpecs = [];
+
+// Enhance the existing XErrorGroupsJSON extension with conditional validation for different error categories
+const enhancedErrorGroupSchema = JSON.parse(fs.readFileSync('src/extensions/schemas/x-error-category-ranges.json', 'utf8'));


Just going to write this here for tracking purposes, that this works as a stopgap until we on the OpenRPC side have a better story for being able to apply extensions to json pointer references. If we have that then there's no need to overwrite the error group spec. You'll able to just push the two specs, here but we're still a little ways from that.

fjl · 2025-10-13T10:04:36Z

One thing to note, is that there is no requirement for RPC errors to be negative numbers. The JSON-RPC specification itself uses a specific range of negative numbers for its errors, but the predefined errors are just for reporting protocol-level faults.

The entire range of positive integer values is available to us, so we should use it.

fjl · 2025-10-13T15:03:11Z

src/extensions/components/execution-errors.yaml

+      message: "EXECUTION_REVERTED"
+      data: "Execution is reverted by REVERT Opcode"
+      x-error-category: "EXECUTION_ERRORS"
+    - code: -31603


Why does this error condition exists here?

#600 just merged has reverted error code = 3 which contradicts this. will this value change?

I will fix this as per our last RPC call, it will still be code = 3

fjl · 2025-10-13T15:03:40Z

src/extensions/components/execution-errors.yaml

+      message: "INVALID_OPCODE"
+      data: "An invalid opcode was encountered during execution"
+      x-error-category: "EXECUTION_ERRORS"
+    - code: -31604


Same with this one, what is the meaning of this particular code? The term "step counters" has no defined meaning in Ethereum.

This is ZK stack specific, I will move this out to a separate category

fjl · 2025-10-13T15:04:47Z

src/extensions/components/rpc-non-standard-errors.yaml

+      - code: -32001
+        message: "Resource not found"
+        data: "Requested resource not found"
+      - code: -32002
+        message: "Resource unavailable"
+        data: "Requested resource not available"


What is the meaning of these two codes? These are very generic errors. I suggest we drop these, since they are not meaningful.

This just reflect the standard we already have
https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1474.md

fjl · 2025-10-13T15:05:22Z

src/extensions/components/txpool-errors.yaml

+    - code: -31009
+      message: "TX_NOT_PERMITTED"
+      data: "Transaction is protected and cannot be permitted for unauthorized users"


What is the meaning of "transaction is protected"

I updated this description

src/extensions/README.md

src/extensions/components/txpool-errors.yaml

Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com>

simsonraj and others added 6 commits February 26, 2025 00:33

sample implementation

510cc9f

Pulling the x-error-groups from open-rpc package

68efb67

updated gastsby & docs generator

b7da3a7

few fixes

46a9906

Merge pull request #1 from simsonraj/error_groups

623c57a

Error groups - Extended open-rpc spec sample implementation

Merge branch 'ethereum:main' into main

2500734

simsonraj changed the title ~~JSON RPC Error codes standardisation: A sample implementation~~ JSON RPC Error codes standardization: A sample implementation May 10, 2025

simsonraj changed the title ~~JSON RPC Error codes standardization: A sample implementation~~ JSON RPC Error codes standardization: Extended Error groups [ Sample implementation] May 10, 2025

simsonraj changed the title ~~JSON RPC Error codes standardization: Extended Error groups [ Sample implementation]~~ JSON RPC Error codes standardization: open-rpc extension specs [A Sample implementation] May 10, 2025

simsonraj mentioned this pull request May 10, 2025

RPC Error code Standardization: Error codes validation implementation using Extended Open-rpc specs lightclient/rpctestgen#42

Open

zcstarr reviewed May 13, 2025

View reviewed changes

scripts/build.js Outdated Show resolved Hide resolved

Update scripts/build.js

721f190

Co-authored-by: Zane Starr <zcstarr@gmail.com>

simsonraj mentioned this pull request May 21, 2025

Standardize JSON-RPC Error codes #658

Open

simsonraj and others added 13 commits June 29, 2025 16:31

meta data extension

3bd6d47

Merge pull request #2 from simsonraj/error_groups

4eacff2

meta data extension

sample implementation

53d5577

Pulling the x-error-groups from open-rpc package

554443e

updated gastsby & docs generator

d3f6f22

few fixes

8d1dd3c

Update scripts/build.js

50113ef

Co-authored-by: Zane Starr <zcstarr@gmail.com>

meta data extension

fc8aacc

Merge pull request #4 from simsonraj/sync_main_again

1ded1ed

Sync main again

fix package conflicts

019a359

fix packages

2b7da45

Merge pull request #5 from simsonraj/sync_main_again

9b06027

Sync main again

extended error categories & code ranges implementation

5c8daea

bomanaps mentioned this pull request Sep 1, 2025

RPC Standards #11 | September 1, 2025 ethereum/pm#1709

Closed

3 tasks

Added TXPOOL errors, README file and fixes

4019acd

simsonraj changed the title ~~JSON RPC Error codes standardization: open-rpc extension specs [A Sample implementation]~~ JSON RPC Error codes standardization using open-rpc extension specs Sep 26, 2025

Added context in README

527bb9a

zcstarr reviewed Sep 29, 2025

View reviewed changes

fjl reviewed Oct 13, 2025

View reviewed changes

src/extensions/README.md Outdated Show resolved Hide resolved

macfarla reviewed Oct 15, 2025

View reviewed changes

macfarla mentioned this pull request Oct 17, 2025

Investigate and fix the Hive rpc-compat issues hyperledger/besu#5377

Open

simsonraj and others added 4 commits October 19, 2025 19:34

Update src/extensions/components/txpool-errors.yaml

89f012f

Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com>

Update src/extensions/components/txpool-errors.yaml

75fb065

Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com>

Update src/extensions/components/txpool-errors.yaml

d3948f7

Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com>

Update src/extensions/components/txpool-errors.yaml

490218e

Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com>

fjl added the triage label Oct 24, 2025

bomanaps mentioned this pull request Oct 25, 2025

RPC Standards # 15 | October 27, 2025 ethereum/pm#1782

Closed

3 tasks

updated & re-organized error ranges & codes after review

8ab56cf

simsonraj requested review from fjl, macfarla and zcstarr October 25, 2025 15:14

fjl removed the triage label Oct 27, 2025

fix ranges

bc78032

Uh oh!

JSON RPC Error codes standardization using open-rpc extension specs #650

Are you sure you want to change the base?

JSON RPC Error codes standardization using open-rpc extension specs #650

Conversation

simsonraj commented May 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goal

Motivation

Solution Abstract

Reserved ranges at a glance

Uh oh!

Uh oh!

sambacha commented May 28, 2025

Uh oh!

zcstarr commented May 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fjl commented Oct 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

macfarla Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

simsonraj commented May 10, 2025 •

edited

Loading

macfarla Oct 15, 2025 •

edited

Loading