File calls
A file call (read, write, stat, readdir, rename, …) names its
failure with one of these conditions, whatever the backend. A service’s own
error becomes the condition it means, such as an object that is not there
becoming ENOENT. One that means none keeps its own words in an exception
and in a shell diagnostic. HTTP returns status 500, and RPC -32603, with
code internal, message internal server error and no errno, since those
words can carry credentials or host paths; they stay in the server’s logs.
Each surface carries the condition its own way:
Shell lines
A line that runs to completion returnsexit_code, stdout and stderr. A
non-zero status is the line’s result, not a failed call: HTTP returns 200, RPC
a result, and MCP sets isError. Canceling the request is a failed call
instead: HTTP returns status 499 and RPC returns error -32800. A command’s stderr
follows GNU coreutils, and its status is the one the real command exits with.
These statuses come from the shell itself:
Service errors
A command that reaches a service through a mount reports the service’s failure as the condition it maps to, or in the service’s own words after the command’s name. An account CLI such asgh or ntn reports
a service error the way the real CLI does, with its wording and exit status.
In code, every backend’s service error extends ApiError (mirage.core.api.errors,
@struktoai/mirage-core/core/api/errors): the service’s message and status, the
HTTP status or null. A service’s own error code stays on its subclass, since code
on a TypeScript error is always the file condition.