ethereum / ethereum/execution-apis

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

Open
#817 14 comments 1 reaction 0 assignees View on GitHub
Dominant language
Io
Stars
1.1k
Forks
530
Avg merge
5d 8h
Merged PRs (30d)
9

Description

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

- #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. #784 and ethereum/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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.