Skip to main content

Module remote_error

Module remote_error 

Source
Expand description

The typed, exhaustive vocabulary of call failures.

A call fails — as opposed to an activation saying no, which is an err item and therefore data — when the service could not or would not run it: no such activation or method, bad params, no credentials, not allowed, or the method itself blew up. The error frame carries exactly one RemoteError, and so does the data of a JSON-RPC-level rejection.

§Wire shape

kind-tagged, snake_case. ParamProblem and DenyReason are flattened into their variant, each under the key its field is named for:

{"kind": "activation_not_found", "activation": "tickets"}
{"kind": "method_not_found", "activation": "tickets", "method": "frob"}
{"kind": "invalid_params", "param": "id", "problem": "missing"}
{"kind": "invalid_params", "param": "id", "problem": "malformed", "detail": "expected a string"}
{"kind": "unauthenticated"}
{"kind": "forbidden", "reason": "missing_scope", "scope": "tickets:write"}
{"kind": "forbidden", "reason": "tenant_boundary"}
{"kind": "handle_not_supported", "activation": "tickets"}
{"kind": "execution", "message": "database is locked"}
{"kind": "forbidden", "reason": "missing_grant", "grant": "tickets.create", "scope": "*", "roles": ["editor", "admin"], "held_on": []}
{"kind": "too_many_calls", "max": 8}
{"kind": "child_unavailable", "child": "echo", "reason": "the connection has closed"}
{"kind": "child_timeout", "child": "echo", "timeout_ms": 5000}

The last four are main’s refusals (AUTH-2’s typed refusal, spec/05’s too_many_calls, spec/12’s child_unavailable and child_timeout), brought into this vocabulary by RETURNS-36: every error frame a server sends carries one RemoteError, beside spec/05’s flattened code / message / error_kind fields.

param is omitted when the failure is not about one parameter (and decodes as None when absent or null).

§Open, typed

A kind this build does not know — menger’s too_many_connections, or too_many_writes with retry_after_ms — is RemoteError::Other: its kind and every other field kept, and written back exactly as it came (RETURNS-36, review #4). A known kind that does not fit its variant is still a decode error. The known variants stay exhaustive for a match; adding one means adding its PlexusError conversion in plexus-core and its mirrors in the Haskell protocol and the TS/Rust generators.

Structs§

OtherError
RemoteError::Other’s content: a kind this build does not know and its other fields, exactly as they came.

Enums§

DenyReason
Why an authenticated caller was refused. Flattened into RemoteError::Forbidden under the reason key.
ParamProblem
What is wrong with a call’s params. Flattened into RemoteError::InvalidParams under the problem key.
RemoteError
Why a call failed — what an error frame carries, and the data of a JSON-RPC-level rejection.