Error codes

This page describes Lasso RPC Core v0.5.0. Cloud has separate access, billing, and rate-limit behavior; see Cloud RPC workload behavior. Core preserves a valid, request-correlated upstream JSON-RPC error’s code, message, and optional data when the upstream HTTP response is 2xx. An error’s numeric code alone does not prove which provider failed or whether repeating the operation is safe.

JSON-RPC envelope

An error response has jsonrpc, id, and an error object with an integer code and string message. data is optional and its shape depends on the source of the error. A valid notification has no response; an all-notification batch returns HTTP 204. Core routes batch items independently.

Code	Meaning	Core example
`-32700`	Parse error	Malformed JSON.
`-32600`	Invalid Request	An invalid request object or empty/oversized batch.
`-32601`	Method not found or unsupported on this transport	`eth_subscribe` over HTTP.
`-32602`	Invalid params	A method’s parameters are invalid.
`-32603`	Internal error	An error reported by Lasso or preserved from an upstream.
`-32000`	Server error	Routing exhausted its eligible attempts.

These are categories, not a promise that every example uses exactly that code. For instance, a valid upstream error can carry its own server-defined code. Core does not issue Cloud API-key, account-quota, or strategy-entitlement errors; protect incoming Core traffic at your deployment boundary.

HTTP subscriptions

The released controller rejects eth_subscribe and eth_unsubscribe over HTTP with -32601 and a WebSocket route hint. Connect through WebSocket endpoints for subscriptions. Core can forward provider-local HTTP filter methods when capability policy permits, with one dispatch and no cross-request affinity. Cloud rejects its documented filter lifecycle locally.

Core routing exhaustion

When no eligible attempt can serve a request, Core v0.5.0 returns a JSON-RPC -32000 error over HTTP 200, preserving the request ID. data has reason, retry_after_ms, and upstream_attempts. retry_after_ms can be non-null only for no_eligible_providers.

`reason`	Meaning	Next action
`no_eligible_providers`	Configured routes are currently unavailable.	Honor a present `retry_after_ms` for a replay-safe request.
`archive_required`	The request needs declared archival support.	Configure and qualify an archival provider.
`transport_unavailable`	No eligible route supports the requested transport.	Configure that transport or change the request.
`no_providers_configured`	The profile has no provider for the chain.	Correct the profile.
`providers_excluded`	Every provider was explicitly excluded.	Review the override or exclusion.
`routing_configuration_changed`	The route changed during selection.	Repeat a replay-safe request against the current configuration.

This serializer fixture uses a fixed retry interval; the live interval depends on current circuit state:

{
  "error": {
    "code": -32000,
    "data": {
      "reason": "no_eligible_providers",
      "retry_after_ms": 5000,
      "upstream_attempts": 0
    },
    "message": "No available channels for method: eth_blockNumber. All circuits open, retry after 5s"
  },
  "id": "client-request-42",
  "jsonrpc": "2.0"
}

The shape comes from the released controller regression and request pipeline. Request metadata can show recorded attempts when available. It does not promise an exhaustive provider diagnostic schema.

Large `eth_getLogs` queries

Core v0.5.0 turns a recognized provider block-range or result-size limit, or its own bounded response-size rejection, into one JSON-RPC error:

{
  "jsonrpc": "2.0",
  "id": "client-request-42",
  "error": {
    "code": -32005,
    "message": "eth_getLogs result exceeds a range or size limit; reduce the block range",
    "data": {
      "reason": "log_range_too_large",
      "action": "reduce_block_range"
    }
  }
}

Retry with a smaller fromBlock–toBlock span and collect the ranges in your application. Lasso does not automatically split the query or try another provider for this deterministic limit. A timeout without a recognized limit does not imply that reducing the range is the only remedy. Other malformed filter arguments retain their original error rather than this action.

Upstream errors and retry safety

An upstream can return a JSON-RPC error body with any HTTP status, but the released Core HTTP client validates and preserves that body only for a 2xx response. HTTP 429, 408, other 4xx, and 5xx statuses are classified as transport or upstream-status failures, even if their body contains a JSON-RPC error. A structurally valid, request-correlated error in a 2xx response keeps its provider code and wording. Gateway text, HTML, and malformed 2xx envelopes are not authoritative JSON-RPC errors. Core can fail over reviewed replay-safe reads within their dispatch budget and absolute deadline. Signed transaction submission receives one upstream dispatch; a lost response may follow acceptance. Reconcile its hash before deciding whether to rebroadcast. Stateful filters and unknown methods have different limits. See the method-safety contract before adding application retries.

WebSocket closure

The released socket closes with code 1002 after two unanswered server heartbeats and 1011 when subscription continuity is exhausted. Other network, server, and proxy closures are possible. Reconnect, recreate the subscription, and use an application checkpoint to recover events missed while the client was disconnected. See connection lifecycle.

HTTP API

WebSocket API

Status and metrics

Reference

Releases and evidence

JSON-RPC envelope

HTTP subscriptions

Core routing exhaustion

Large `eth_getLogs` queries

Upstream errors and retry safety

WebSocket closure

​JSON-RPC envelope

​HTTP subscriptions

​Core routing exhaustion

​Large eth_getLogs queries

​Upstream errors and retry safety

​WebSocket closure

JSON-RPC envelope

HTTP subscriptions

Core routing exhaustion

Large `eth_getLogs` queries

Upstream errors and retry safety

WebSocket closure