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
- 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

Error groups - Extended open-rpc spec sample implementation

scripts/build.js

Co-authored-by: Zane Starr <[email protected]>

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 <[email protected]>

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?

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.

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.

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"

fjl · 2025-10-13T15:10:01Z

src/extensions/README.md

+## Catalog reference
+
+### [JSON-RPC standard errors](https://www.jsonrpc.org/specification) (`rpc-standard-errors.yaml`)
+| Code | Message | Notes |
+| --- | --- | --- |
+| $-32700$ | Parse error | 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 |
+
+### [JSON-RPC non-standard errors](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1474.md) (`rpc-non-standard-errors.yaml`)
+| Code | Message | Notes |
+| --- | --- | --- |
+| $-32000$ | Invalid input | Missing or invalid parameters |
+| $-32001$ | Resource not found | Requested resource not found |
+| $-32002$ | Resource unavailable | Requested resource not available |
+| $-32003$ | Transaction rejected | Transaction creation failed |
+| $-32004$ | Method not supported | Method is not implemented |
+| $-32005$ | Limit exceeded | Request exceeds defined limit |
+| $-32006$ | JSON-RPC version not supported | Version of JSON-RPC protocol is not supported |
+
+### Gas errors (`gas-error-groups.yaml`)
+| Code | Message | Data |
+| --- | --- | --- |
+| $-31800$ | GAS_TOO_LOW | Transaction gas is too low / intrinsic gas too low |
+| $-31801$ | OUT_OF_GAS | The transaction ran out of gas |
+| $-31802$ | GAS_PRICE_TOO_LOW | Gas price too low / gas price below configured minimum gas price |
+| $-31803$ | BLOCK_GAS_LIMIT_EXCEEDED | Tx gas limit exceeds max block gas limit / intrinsic gas exceeds gas limit |
+| $-31804$ | FEE_CAP_EXCEEDED | Tx fee exceeds cap / max priority fee per gas higher than max fee per gas |
+| $-31805$ | GAS_OVERFLOW | Gas overflow error |
+| $-31806$ | INSUFFICIENT_TRANSACTION_PRICE | Transaction price must be greater than base fee / max fee per gas less than block base fee |
+| $-31807$ | INVALID_MAX_PRIORITY_FEE_PER_GAS | Max priority fee per gas higher than $2^{256}-1$ |
+| $-31808$ | INVALID_MAX_FEE_PER_GAS | Max fee per gas higher than $2^{256}-1$ |
+| $-31809$ | INSUFFICIENT_FUNDS | Insufficient funds for gas * price + value |
+| $-31810$ | TRANSACTION_UNDERPRICED | Transaction's gas price is below the minimum for txpool |
+| $-31811$ | REPLACEMENT_TRANSACTION_UNDERPRICED | Replacement transaction is sent without the required price bump |
+
+### Execution errors (`execution-errors.yaml`)
+| Code | Message | Data |
+| --- | --- | --- |
+| $-31600$ | NONCE_TOO_LOW | Transaction nonce is lower than the sender account's current nonce |
+| $-31601$ | NONCE_TOO_HIGH | Transaction nonce is higher than the sender account's current nonce |
+| $-31602$ | EXECUTION_REVERTED | Execution is reverted by REVERT Opcode |
+| $-31603$ | INVALID_OPCODE | An invalid opcode was encountered during execution |
+| $-31604$ | OUT_OF_COUNTERS | Not enough step counters to continue the execution |
+
+### TxPool errors (`txpool-errors.yaml`)
+| Code | Message | Data |
+| --- | --- | --- |
+| $-31000$ | ALREADY_KNOWN | Transaction is already known to the transaction pool |
+| $-31001$ | INVALID_SENDER | Transaction sender is invalid |
+| $-31002$ | INVALID_SIGNATURE | Transaction signature is invalid |
+| $-31003$ | TXPOOL_FULL | Transaction pool is full |
+| $-31004$ | NEGATIVE_VALUE | Transaction with negative value |
+| $-31005$ | OVERSIZED_DATA | Transaction input data exceeds the allowed limit |
+| $-31006$ | SENDER_BLACKLISTED | Transaction sender is blacklisted |
+| $-31007$ | RECEIVER_BLACKLISTED | Transaction receiver is blacklisted |
+| $-31008$ | CHAIN_ID_MISMATCH | Transaction chain ID does not match the expected chain ID |
+| $-31009$ | TX_NOT_PERMITTED | Transaction is protected and cannot be permitted for unauthorized users |
+| $-31010$ | INVALID_RLP_DATA | Transaction Data contains invalid RLP encoding |


Please do not re-list all the errors in this document.

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 <[email protected]>

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 <[email protected]>

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

simsonraj commented May 10, 2025 •

edited

Loading

Uh oh!

Uh oh!

sambacha commented May 28, 2025

Uh oh!

zcstarr commented May 28, 2025

Uh oh!

zcstarr Sep 29, 2025

Uh oh!

fjl commented Oct 13, 2025

Uh oh!

fjl Oct 13, 2025

Uh oh!

fjl Oct 13, 2025

Uh oh!

fjl Oct 13, 2025

Uh oh!

fjl Oct 13, 2025

Uh oh!

fjl Oct 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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

Uh oh!

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

Uh oh!

Uh oh!

sambacha commented May 28, 2025

Uh oh!

zcstarr commented May 28, 2025

Uh oh!

zcstarr Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

fjl commented Oct 13, 2025

Uh oh!

fjl Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

fjl Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

fjl Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

fjl Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

fjl Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

simsonraj commented May 10, 2025 •

edited

Loading