Module error 

The canonical DIG-node RPC error taxonomy.

This module is the single definition point for every error code the DIG node RPC surface emits, the canonical RpcError envelope ({code, message, data:{code, origin}}), and the one constructor helper both node implementations call so every error carries a machine-branchable data.code and data.origin.

The code set

Standard JSON-RPC 2.0 codes plus the DIG protocol-specific codes. The numeric values are a published wire contract and never change once assigned.

Code	Variant	Origin	Meaning
-32700	ParseError	Node	request body is not valid JSON
-32600	InvalidRequest	Node	not a valid Request object
-32601	MethodNotFound	Node	method not implemented
-32602	InvalidParams	Node	missing/malformed params
-32603	InternalError	Node	well-formed call failed
-32000	ServerError	Node	generic server error
-32003	ContentMissRateLimited	Node	content not held; miss-lookup budget exhausted for this requestor
-32004	ResourceUnavailable	Node	resource not available at the requested root (genuine infra miss)
-32005	RootNotAnchored	Node	requested/served root is not the chain-anchored root (fail-closed pin)
-32006	PeerUnreachable	Node	no NAT-traversal strategy reached the peer
-32007	RangeNotSatisfiable	Node	byte range lies outside the resource
-32008	ContentRedirect	Node	content held elsewhere — data.redirect names holders
-32009	RangeMetadataUnrepresentable	Node	the resource’s own range metadata cannot fit a conforming frame, so this holder can NEVER serve the range
-32010	UpstreamError	Upstream	an upstream/proxy fetch failed
-32011	StageInvalidInput	Node	dig.stage: dir unreadable / walk budget exceeded
-32012	StageNoFiles	Node	dig.stage: no files to compile
-32013	StageOverCap	Node	dig.stage: input exceeds the store cap
-32014	StageCompileFailed	Node	dig.stage: compile / IO failure
-32015	MetadataTooLarge	Node	dig.getMetadata: the metadata section is refused as too large/complex (bounded error)
-32016	PushPendingLimited	Node	cache.pushCapsule: refused, the pending-push budget is exhausted
-32017	ContentMissInconclusive	Peer	absence was NOT established — a hop timed out, was unreachable, or refused uninformatively
-32020	OnionCircuitUnavailable	Onion	private read could not build/keep a circuit
-32021	PrivacyRequiresLocalNode	Onion	privacy mode requires the caller be a local originator
-32022	OnionHopsOutOfRange	Onion	requested hop count outside [2, 5]
-32030	Unauthorized	Control	control-plane call is not authorized
-32031	NotSupported	Control	control-plane method not supported here
-32032	ControlError	Control	control-plane runtime error
-32050	NoIdentity	Node	no persistent identity key, so the node cannot seal as sender
-32051	NoPeerNetwork	Peer	no gossip pool, so a directed send has no transport
-32052	SendFailed	Peer	sealing or sending the directed message failed

The -32020..-32022 collision, resolved

The published normative protocol (docs.dig.net) assigns -32020/-32021/-32022 to the onion (private-retrieval) failures. Those keep their numbers. The control-plane errors that previously squatted the same values are renumbered to -32030/-32031/-32032.

The canonical space includes consumer-held ranges

A number is free only if it is unoccupied ECOSYSTEM-WIDE, not merely absent from ErrorCode::ALL. Consumers hold undeclared bands inside this same space: -32015 METADATA_TOO_LARGE and -32016 PUSH_PENDING_LIMITED were released, catalogued on docs.dig.net, and emitted by dig-node while being invisible here, so ContentMissInconclusive was assigned -32015 as “the next free code” and collided with a live wire contract. That was the second such collision on one variant (-32009 was the first).

Those five consumer-held codes are now DECLARED here with their existing numbers and meanings unchanged — the canonical side adapts, because a released code is a published branch key and renumbering one breaks clients (§5.1 is additive-only). The band map, so the next assignment has somewhere to look:

Band	Owner
-32000..-32019	node read/serve + staging
-32020..-32029	onion / private retrieval
-32030..-32039	loopback control plane
-32040..-32049	control-plane wallet reads (consumer-held, not yet absorbed)
-32050..-32059	directed messaging — sealed sender-to-recipient sends

-32050..-32052 get a band of their own rather than joining the control band: they are served on the node’s ORDINARY JSON-RPC surface (dispatched from seams::dig_rpc, reusing the standard -32602 for bad params), so they are neither control-plane nor “the node’s private application range” — a directed send is a peer-network operation and is banded as one.

tests/error_code_registry.rs holds the measured occupancy as data and asserts no declaration contradicts it. See that file for what the list can and cannot prove.

Structs

ErrorData

Structured error context carried in error.data.

RpcError

The canonical DIG-node RPC error object: {code, message, data:{code, origin}}.

Enums

ErrorCode

A canonical DIG-node RPC error code.

ErrorOrigin

The subsystem a failure arose in — carried in data.origin so a client can route the error (retry upstream, rebuild a circuit, re-auth the control plane) without parsing the message.