Inconsistent JSON-RPC error codes for the same transaction-validation failure modes across methods

[MysticRyuujin]

Summary

The spec currently defines two different JSON-RPC error codes for the same transaction-validation failure modes, depending on which method returns the error.

Details

• all: error codes standardization with error grouping #650 (merged) introduced a shared error-code catalog in src/error-groups/ using positive codes — e.g. ExecutionErrors (1–199), GasErrors (800–999), TxPoolErrors (1000–1199). These groups are referenced by eth_sendTransaction / eth_sendRawTransaction.
• src/eth/execute.yaml defines eth_simulateV1 errors using the -38xxx and -32xxx ranges for the same failure modes (these predate all: error codes standardization with error grouping #650).

For identical conditions, the two schemes assign different codes:

Failure mode	Catalog code (#650)	eth_simulateV1 code (execute.yaml)
Nonce too low	1	-38010
Nonce too high	2	-38011
Intrinsic gas too low	800	-38013
Max fee per gas too low	802	-32005
Block gas limit exceeded	803	-38015
Max priority fee per gas higher than max fee per gas	804	-32602 (generic)
Max fee per gas below base fee	806	-38012
Max priority fee per gas higher than 2^256-1	807	-32602 (generic)
Max fee per gas higher than 2^256-1	808	-32602 (generic)
Insufficient funds	809	-38014

The -32602 (generic) rows are conditions for which eth_simulateV1 has no dedicated code and falls back to the generic "invalid params" code, rather than a distinct one. The remaining rows are codes explicitly listed in execute.yaml.

This list may not be exhaustive.

• error-groups, tools, tests: add spec-mandated error-code fixtures for methods #784 (open) references the catalog error groups (ExecutionErrors, GasErrors) from eth_call, eth_estimateGas, and eth_simulateV1, without removing the existing -38xxx / -32xxx codes from eth_simulateV1. As written, eth_simulateV1's resolved errors[] would list both codes (e.g. 800 and -38013) for the same failure mode.

Status

• The catalog codes are in the early stages of client implementation (e.g. error-groups, tools, tests: add spec-mandated error-code fixtures for methods #784 and internal/ethapi: return standardized error codes for transaction submission go-ethereum#35105).
• The -38xxx codes for eth_simulateV1 are already specified and implemented.

Decision needed

Should a given failure mode use a single error code across all methods? If so, which scheme is authoritative and what is the migration path for the other? Or should per-method codes be retained as they are?

Opening this to gather core-dev feedback before error-code standardization proceeds further.

[lightclient]

1. seems good to use standardized error codes across methods
2. I think eth_simulate uses the large negative codes because the JSON-RPC reads as if user defined errors should be in that range, but it isn't really a requirement. So that's why IIRC in the catalog codes they went with the smaller positive range. So I'm not sure how difficult it will be migrate the simulate method. Probably need eth_simulateV2 to roll out with the new errors and add deprecation notice to eth_simulateV1. It will take time.

[s1na]

Agree on 1.

On 2: fair that JSON-RPC doesn't require user defined errors to be in the large negative range. But I'd push back on treating this just as a simulate migration. The -38xxx range is used beyond eth_simulateV1 and particularly in Engine API methods. Really the main positive error codes currently in production are 3 for revert (which is consistent across the board) and 4444 for history expiry (which is taken from the EIP number).

The eth_simulateV2 rollout can take months if not more. I'd like us to consider the alternative: aligning the catalog with the existing -38xxx codes instead, which would avoid the method migration.

[lightclient]

Wasn't trying to say it was just eth_simulate 😄 I also thought error codes were supposed to be -38xxx when we were working on the Engine API 😅

I think the main two questions are:

• Do the error codes in all: error codes standardization with error grouping #650 provide demonstrable benefit over -38xxx style? Either via improved readability or improved categorization?
• How disruptive / expensive is it to migrate to the all: error codes standardization with error grouping #650-style codes in eth_simulate?

From my POV it seems #650-style does provide some benefit, and I can't speak to the migration of eth_simulate.

Ultimately I'm okay either way, just want to be sure we don't have two different error code ranges covering same errors. What's the best way to come to consensus on this? Should we quickly check on ACD?

[luanxu-dev]

One way to make the trade-off less preference-based would be to separate the semantic category from the numeric wire code.

A small matrix for each failure mode (sendTransaction / sendRawTransaction / simulate / engine users) could record:

• current code;
• clients known to branch on it;
• whether the code is consensus-critical or tooling-only;
• whether a stable semantic tag can be exposed in docs/tests before any numeric migration.

If #650-style codes win on readability/categorization, the migration could still be staged as: keep existing numeric codes on V1 methods, add conformance tests that map both families to the same semantic failure keys, and only introduce new numeric codes on an explicitly versioned method or capability.

That would avoid forcing wallets, relays, and simulators to guess whether nonce too low changed meaning when only the method changed.

[MysticRyuujin]

The "problem" is that only eth_simulate is versioned, and there's not much appetite to start doing eth_callV2 etc.

It's a "breaking change" if codes are relied on, but codes have notoriously not been standardized so people really couldn't rely on them in the first place 😅

The path of least resistance is probably either to leave eth_simulateV1 alone, plan on doing a V2 eventually, or change the catalog, which is new enough that it probably won't break anything to just change the catelog.

I'm fine with either...

[lightclient]

@luanxu-dev I'm sorry I don't understand your suggestion, can expand?

[luanxu-dev]

By “semantic tag” I mean something smaller than a new wire code: give each failure mode a stable spec/test identifier first, then let each method keep (or later version) its numeric JSON-RPC code separately. For example, a fixture row could be tx.validation.nonce_too_low with columns for eth_sendRawTransaction, eth_simulateV1, and Engine API current code, plus a note whether that numeric code is legacy/stable/new. Clients and tests can then agree that these rows describe the same failure even if V1 methods keep their existing numbers. That would let the catalog discussion happen without requiring an immediate numeric migration: first add the semantic rows + conformance tests, then only assign #650-style numbers to a versioned method/capability if the group decides the readability win is worth a wire change.

[lightclient]

Ah I see. A text identifier for the error could be nice in general too?

[MysticRyuujin]

@simsonraj do you have any input as the author of #650?

[simsonraj]

Thanks for getting this discussion going.

A. Catalog wins. Migrate eth_simulateV1 from -38xxx to the positive-int catalog. Engine API could stay in -38xxx as its own EngineErrors group along the Standard & NonStandardJSON error groups

B. -38xxx wins. Revise the catalog into the -38xxx band. Two structural problems with this:

1. the current simulate error codes doesn't match the error grouping/ranges as the catalog defines today, even with a rewrite to negative integers. For example, ExecutionErrors (-38010..-38011) and GasErrors (-38012..-38015) are interleaved in the same numeric range
2. Codes that already exist outside -38xxx (3 for revert, 4444) non uniform ranges

Net effect of B can be solved by "semantic tag" & let consumers do code-to-group lookup via the spec rather than range-check. And that was also actually proposed, but the decision was to keep it simple and adopt standard errors instead of versioning them and slowly push for adoption (exactly why Simulate method was out of scope for this one)

The primary goal of #650 was web2-style readability — a developer/user should be able to glance at the code and know the category, the way 4xx vs 5xx works for HTTP. That property only holds if codes are grouped by numeric range.
So as @MysticRyuujin mentioned, given the simulateV1 is early in adoption it would be good to convert them to the new standard or leave it alone by maintaining a matrix somewhere without branching versions and tackle it in v2? ( and of course we could also get opinions from ACD)

@fjl would be good to get your opinion here

[fjl]

Sorry it took me a while to get to this PR. Today also discussed it in a meeting with @s1na. So here is my input:

We added the tooling for error codes in #784 but the specific codes were anyway up for debate. I do think there are still some weird ones in there (JSONRPCNonStandardErrors???) and we have the full choice right now since almost nothing is standardized and just returns generic errors. We should really go through the list and clean up the available codes.

That said, I like the idea of splitting error groups into ranges as much as possible, since it maps nicely to exception categories in clients. @s1na suggests that we could simply merge the 'gas errors' and 'execution errors' to restore compatibility with eth_simulateV1.

On the topic of using eth_simulateV1 codes, it is true that this method was there first, and thus established some codes for certain situations. However, it is a weird method in that some of the errors will only ever be returned in relation to a specific transaction, and thus the error will never actually be a real JSON-RPC error, it's just a result code. So should we stick to these errors? It is easier and less changes....

[fjl]

About some of these new codes, things like "Max fee per gas higher than 2^256-1" is just an "invalid parameters" condition. So there is no need to define a separate error code.

[MysticRyuujin]

I'm gonna try to summarize the conversation(s) into what I think we're proposing as a compromise to move forward:

• Keep the -38xxx codes for eth_simulateV1 as-is. A lot of them only show up in relation to a specific tx in the bundle, so they read more like per-tx result codes than true JSON-RPC errors and tools already depend on them (per @KillariDev). Rather than change them in place, plan to move to the catalog codes in a future eth_simulateV2.

• Do a cleanup pass on the catalog before wiring it in further: drop entries that are really just "invalid params" (e.g. max fee > 2²⁵⁶−1), sort out the odd groups like JSONRPCNonStandardErrors.

In order to do this we need a new PR to do a cleanup of the error groups and then #784 updates to reflect the cleaned-up groups (the eth_call / eth_estimateGas refs).