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§
- Other
Error RemoteError::Other’s content: a kind this build does not know and its other fields, exactly as they came.
Enums§
- Deny
Reason - Why an authenticated caller was refused. Flattened into
RemoteError::Forbiddenunder thereasonkey. - Param
Problem - What is wrong with a call’s params. Flattened into
RemoteError::InvalidParamsunder theproblemkey. - Remote
Error - Why a call failed — what an error frame carries, and the
dataof a JSON-RPC-level rejection.