Error codes

Omega has multiple, distinct ways something can go wrong. Each has its own type. They are NOT interchangeable.

FAILURE_CODES — the Outcome family

projects/omega-lisp/src/core/outcome.ts:4-13:

export const FAILURE_CODES = [
  "invalid_input",
  "not_found",
  "conflict",
  "unauthorized",
  "forbidden",
  "timeout",
  "unavailable",
  "internal_error",
] as const;

This is the canonical set of result-style failure codes used by helper APIs that return Outcome<T> (an Ok<T> or Err<Failure>).

Code	When
invalid_input	bad arguments — type mismatch, malformed data
not_found	the requested entity does not exist
conflict	the operation conflicts with current state
unauthorized	the caller is not authenticated
forbidden	authenticated but not allowed
timeout	exceeded a time budget
unavailable	upstream service down or capacity exhausted
internal_error	an unexpected condition; not the caller's fault

Outcome<T> shape

type Ok<T>      = { tag: "Ok";  value: T;        diagnostics: Diagnostic[] }
type Err<F>     = { tag: "Err"; failure: F }
type Outcome<T> = Ok<T> | Err<Failure>

type Failure = {
  code: FailureCode;
  message: string;
  diagnostics: Diagnostic[];
  cause?: unknown;
  data?: Record<string, unknown>;
}

Helper builders: ok(value), err(code, message, options), failure(...), plus warn, info, error for Diagnostic construction. All exported from omega-lisp/src/index.ts:13-32.

Diagnostic

type Diagnostic = {
  message: string;
  severity: "error" | "warning" | "info";
  span?: { file?: string; start: { line: number; column: number; offset? }; end?: ... };
  code?: string;
  source?: string;
  data?: Record<string, unknown>;
}

Diagnostics carry source position (compiler errors), severity classification, and arbitrary structured data. They are NOT errors; they're reports attached to results.

ConditionVal — structured exceptions

core/conditions/types.ts. Conditions are first-class values raised with signal/raise and caught with handler-case. Unlike Outcome, which is a return shape, conditions interrupt control flow.

(handler-case
  (begin
    (when (negative? x)
      (signal 'overflow "x must be non-negative" :data x))
    (sqrt x))
  ((overflow c)
    (display "overflow: ")
    (display (condition-message c))
    nil))

ErrVal — value-level errors

{ tag: "Err"; ... } — a value tagged with Err that some primitives return when they want to return an error rather than signal one. Often used by speculative or backtracking code that would lose context if it threw.

Contradiction — constraint-network outcome

{ tag: "Contradiction"; explanation: ExplanationVal; ... } — produced when a constraint network detects an inconsistency. Not an exception. Pass to (repair net contradiction :options ...) to synthesize fixes.

Agent error codes (separate from this taxonomy)

The Matrix Agent Platform has its own error code set in AgentActor.MX_AGENT_ERRORS (AGENT_BUSY, AGENT_TIMEOUT, LLM_API_FAILURE, etc.). Those are documented in the agent-platform docs. Omega and Matrix do not share an error code namespace.

Driver error class

InferenceError (projects/omega-drivers/packages/inference/src/index.ts:209-224) carries an errorClass:

"network" | "auth" | "rate-limit" | "timeout" | "invalid-response" | "capability-mismatch"

When an Omega oracle call fails, the resulting Err<Failure> typically maps the InferenceError.errorClass onto a FailureCode:

InferenceError.errorClass	maps to FailureCode
network	unavailable
auth	unauthorized
rate-limit	unavailable
timeout	timeout
invalid-response	internal_error
capability-mismatch	invalid_input

See also

• CLI / REPL for the CLI exit codes
• Language Guide: Evaluation for raising/handling
• Forms for condition, signal, handler-case

Source: projects/omega-lisp/src/core/outcome.ts:1-79, projects/omega-lisp/src/core/conditions/types.ts, projects/omega-drivers/packages/inference/src/index.ts:209-224.