# error_decode_json

Returns a status-rich JSON description of EVM revert bytes; supply an ABI to decode matching custom errors.

Canonical HTML: <https://determica.com/docs/functions/error_decode_json>

- Kind: scalar function
- Category: [Contracts and ABI](/docs/category/contracts-and-abi.md)
- Tags: Evm Encoding, ABI, Diagnostics

Returns a status-rich JSON description of EVM revert bytes; supply an ABI to decode matching custom errors.

## Overload 1: error_decode_json(BYTES)

```sql
error_decode_json(BYTES)
```

Decodes raw revert bytes without an ABI registry lookup.

- Kind: scalar
- Execution context: Offline
- Behavior: Builtin Or Raw Error Diagnostic
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: JSON
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `revert_data` (BYTES; required; positional) — Raw revert bytes returned by a failed eth_call or simulated execution.

### Returns

Revert diagnostic JSON

Fields by decode_status: decoded has selector, signature, name, and args; unknown has selector (possibly null), raw, and payload_words; ambiguous has selector; decode_error has error, raw, and selector when available.

- `diagnostic` (JSON)

Revert diagnostic JSON. Fields by decode_status: decoded has selector, signature, name, and args; unknown has selector (possibly null), raw, and payload_words; ambiguous has selector; decode_error has error, raw, and selector when available.

### Examples

_Local SQL · Local_

```sql
SELECT error_decode_json(
  error_selector('Panic(uint256)')::BYTES || evm_abi_word(17::UINT256)::BYTES
) AS diagnostic;
-- diagnostic.decode_status = decoded
```

## Overload 2: error_decode_json(JSON, BYTES)

```sql
error_decode_json(JSON, BYTES)
```

Decodes revert bytes with JSON ABI error definitions.

- Kind: scalar
- Execution context: Offline
- Behavior: Abi Error Diagnostic
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: JSON
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `abi` (JSON; required; positional) — Contract ABI JSON containing error definitions.
- `revert_data` (BYTES; required; positional) — Raw revert bytes returned by a failed call.

### Returns

Revert diagnostic JSON

Fields by decode_status: decoded has selector, signature, name, and args; unknown has selector (possibly null), raw, and payload_words; ambiguous has selector; decode_error has error, raw, and selector when available.

- `diagnostic` (JSON)

Revert diagnostic JSON. Fields by decode_status: decoded has selector, signature, name, and args; unknown has selector (possibly null), raw, and payload_words; ambiguous has selector; decode_error has error, raw, and selector when available.

### Examples

_Local SQL · Local_

```sql
SELECT error_decode_json(
  '[{"type":"error","name":"ERC20InsufficientBalance","inputs":[{"name":"sender","type":"address"},{"name":"balance","type":"uint256"},{"name":"needed","type":"uint256"}]}]'::JSON,
  error_selector('ERC20InsufficientBalance(address,uint256,uint256)')::BYTES
    || evm_abi_word('0xcb83ca9633ad057bd88a48a5b6e8108d97ad4472'::ADDRESS)::BYTES
    || evm_abi_word(500000000::UINT256)::BYTES
    || evm_abi_word(615568393::UINT256)::BYTES
) AS diagnostic;
-- diagnostic.name = ERC20InsufficientBalance
```

## Overload 3: error_decode_json(VARCHAR, BYTES)

```sql
error_decode_json(VARCHAR, BYTES)
```

Decodes revert bytes with VARCHAR ABI error definitions.

- Kind: scalar
- Execution context: Offline
- Behavior: Abi Error Diagnostic
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: JSON
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `abi` (VARCHAR; required; positional) — Contract ABI JSON containing error definitions.
- `revert_data` (BYTES; required; positional) — Raw revert bytes returned by a failed call.

### Returns

Revert diagnostic JSON

Fields by decode_status: decoded has selector, signature, name, and args; unknown has selector (possibly null), raw, and payload_words; ambiguous has selector; decode_error has error, raw, and selector when available.

- `diagnostic` (JSON)

Revert diagnostic JSON. Fields by decode_status: decoded has selector, signature, name, and args; unknown has selector (possibly null), raw, and payload_words; ambiguous has selector; decode_error has error, raw, and selector when available.

### Examples

_Local SQL · Local_

```sql
SELECT error_decode_json(
  '[{"type":"error","name":"ERC20InsufficientBalance","inputs":[{"name":"sender","type":"address"},{"name":"balance","type":"uint256"},{"name":"needed","type":"uint256"}]}]'::VARCHAR,
  error_selector('ERC20InsufficientBalance(address,uint256,uint256)')::BYTES
    || evm_abi_word('0xcb83ca9633ad057bd88a48a5b6e8108d97ad4472'::ADDRESS)::BYTES
    || evm_abi_word(500000000::UINT256)::BYTES
    || evm_abi_word(615568393::UINT256)::BYTES
) AS diagnostic;
-- diagnostic.name = ERC20InsufficientBalance
```

## Guidance

### Inspect failed calls

Use error_decode_json when a read, preflight, or local execution returns revert bytes and you need a reviewable row explaining the failure. Required NULL inputs propagate NULL.

- Use the ABI overload when you already have the contract ABI.
- Use evm_decode_revert_for when the ABI has been registered for a chain/address/block context.
- A decoded registry-backed custom error adds abi_label when the selected registration has a label.
- Keep the raw revert bytes in evidence rows when the decoded name is not enough for review.

## Related functions

- [error_selector](/docs/functions/error_selector.md) — Usually After
- [error_selector_json](/docs/functions/error_selector_json.md) — Usually After
- [evm_decode_revert_for](/docs/functions/evm_decode_revert_for.md) — Alternative
- [evm_register_contract_abi](/docs/functions/evm_register_contract_abi.md) — Usually Before