provider.rpc_failure

Documentation for eth_defi.provider.rpc_failure Python module.

Classify upstream JSON-RPC failures into a small, stable set of modes.

Turns a heterogeneous provider error — an HTTP status, a JSON-RPC error body, a requests timeout, or a raw exception — into one obvious RpcFailureMode so test output and CI logs name why an archive RPC call failed (“out of credits”, “rate limited”, “read timeout”) instead of a generic stack trace.

This exists because shared Anvil mainnet-fork tests fail environmentally when their upstream archive provider is exhausted or throttled under concurrent load (see eth_defi.testing.anvil_fork_pool and docs/README-test-suite-performance.md). When that happens, an operator reading the CI log needs to see the provider and the failure mode immediately, not a bare eth_chainId RuntimeError.

Classification is best-effort and deliberately conservative: an unrecognised failure returns RpcFailureMode.unknown rather than being force-fit into a specific mode, so the label never misleads.

Functions

classify_rpc_failure(error)

Classify an upstream JSON-RPC failure into a RpcFailureMode.

Classes

RpcFailureMode

Coarse, stable classification of an upstream JSON-RPC failure.

class RpcFailureMode

Bases: enum.Enum

Coarse, stable classification of an upstream JSON-RPC failure.

Values are snake_case strings safe to log, aggregate and grep in CI output.

out_of_credits = 'out_of_credits': Provider rejected the request for billing/quota reasons (HTTP 402, or a message mentioning credits/compute units/quota/plan limits).

rate_limited = 'rate_limited': Provider throttled the request (HTTP 429, “too many requests”, throttling).

read_timeout = 'read_timeout': The request exceeded its read timeout (requests ReadTimeout / Timeout).

connection_error = 'connection_error': Could not establish or keep a connection (refused, reset, DNS, pool).

server_error = 'server_error': Upstream returned a 5xx (bad gateway, service unavailable, gateway timeout).

bad_response = 'bad_response': A response arrived but was malformed / not valid JSON-RPC.

unknown = 'unknown': Nothing matched — do not guess.

classify_rpc_failure(error)

Classify an upstream JSON-RPC failure into a RpcFailureMode.

Inspection order: concrete requests timeout/connection types first (the most reliable signal), then the normalised HTTP status code, then message substrings. Falls back to RpcFailureMode.unknown when nothing matches — the label is only ever set when there is positive evidence.

Parameters: error (Union[BaseException, dict, str]) – A raised exception, a JSON-RPC error dictionary, or an error string.
Returns: The best-effort failure mode.
Return type: eth_defi.provider.rpc_failure.RpcFailureMode