Errors

One shape crosses every boundary: ArbeError. Both the throwable class — internals throw new ArbeError({ code, message, suggestion?, recoverable?, context? }) instead of bare Error — and the validated wire schema HTTP and CLI surfaces emit. code is dotted lowercase, namespaced by domain (task.already_claimed, validation.invalid_input, auth.forbidden, agent.dispatch_failed). Grow the enum by adding; never renumber or reuse.

HTTP            { error: ArbeError.toJSON() }      status from code map (no per-throw override)
CLI stderr      error: <message>                    →  <suggestion>
CLI --json      { error: ArbeErrorPayload }        identical to HTTP body
JS client       rejects with parsed ArbeError instance

HTTP status derives from code via a single map — if you need a new status for an existing code, add a new code instead. This rules out “record.not_found that returns 500” by construction. Boundary layers (SvelteKit +server handlers, worker routes, apps/cli/src/cli.ts) catch ArbeError, log the underlying cause, serialise. Unknown throws go through toArbeError() which wraps them as server.internal with the original as cause so crashes still render through the canonical path.

Internal helpers that never cross a boundary still throw native Error — cheap, idiomatic, won’t change. Code a consumer will see the failure of (CLI commands, HTTP endpoints, mutation executors) throws ArbeError. The line between “internal” and “boundary-facing” is the discriminator between developers-see-this-in-logs and users-see-this-on-their-screen — when in doubt, throw ArbeError; the cost is one import and one extra field.

We explicitly rejected the Result<Success|Failure> discriminated-union pattern. Throws propagate; only boundaries catch. Wrapping every function’s return type in a union is ceremony arbe’s code-style argues against (“optimistic execution — let errors throw”). ArbeError is the shape, not the protocol. When a new failure mode is genuinely a variant of an existing code, prefer reusing the code and putting distinguishing detail in message / context rather than minting a new code — codes are for switches that branch consumer behaviour; messages are for humans.

Code: @arbe/errors (ArbeError, ArbeErrorCodeSchema, toArbeError), re-exported via @arbe/core/schemas/arbe-error. Boundary catchers: SvelteKit +server handlers, worker routes, apps/cli/src/cli.ts.