Skip to main content
Every error Nika emits is a typed structure with a stable code, a category, and a transient flag the retry machinery reads. The format is NIKA-<NAMESPACE>-<NNN>. An optional sub-namespace self-documents builtin errors (NIKA-BUILTIN-WAIT-001). The full grammar:
The tables below are the specification’s registry. The reference engine adds two kinds of codes on top of it:
  • Runtime codes NIKA-<NNNN>: 17xx for admission and budget (NIKA-1708 a missing required input, NIKA-1709 a run refused before it starts because its cost floor exceeds the budget or a paid image or speech call has no price under a cap, NIKA-1704 a budget stop mid-run or a paid media call refused just before its request, NIKA-1707 a run whose check report did not resolve a child workflow call) and 18xx for access (NIKA-1800 no ready access path, or a declared run.access selection its route cannot carry, such as a service_tier outside the Codex seat over ACP; NIKA-1801 an unsatisfied --access pin; NIKA-1804 and NIKA-1805 a turn an agent application reported as failed, transient or not, and NIKA-1805 also a service_tier the session cannot confirm before the prompt; NIKA-1806 a pause on an agent application’s question). nika explain NIKA-1709 teaches each one.
  • Engine-specific codes outside the spec registry. The MCP pin refusals NIKA-MCP-003 to NIKA-MCP-006 (a server whose tools drifted from their pins, an untrusted .nika/mcp_pins.json, a server the OS sandbox cannot confine, a tool that was never approved) each print their remedy, and nika explain answers them, nika mcp approve <server> included. The message itself explains others, such as NIKA-REG-005 (a registry index this engine cannot read).
Canonical source: spec/05-errors.md owns the taxonomy: engines derive from it, never the reverse. The machine-readable registry lives in the spec’s canon.yaml and is also served as JSON at nika.sh/errors/catalog.json. The tables below are generated from that registry.

The error shape

transient: true means a retry might succeed. retry: only fires on transient errors (unless on_codes: widens it). on_error: catches the final error either way, and on_error.on_codes routes recovery by exact code.

Categories

The registered codes (v0.1 normative floor)

A conformant engine emits exactly these codes for these failures. Engines may add codes within a namespace’s 001-099 range. Never repurpose one.

Retired codes (never reuse)

Two allocation holes in the table above are deliberate — a retired code is never repurposed:
  • NIKA-PARSE-016 — the jq-binding-contains-template class folded into NIKA-VAR-005.
  • NIKA-DAG-003 — « a tasks.X reference with no declared edge » became inexpressible in W2 « the flow »: the with: binding IS the edge (derived, never restated), and a reference outside the boundary is NIKA-VAR-021.

Namespaces

Builtin errors use a per-builtin sub-namespace: each builtin owns its own 001-099 (NIKA-BUILTIN-FETCH-001 is the fetch tool’s network/extraction failure). Underscore-named builtins encode naturally: NIKA-BUILTIN-JSON_MERGE_PATCH-001.

Routing on codes

on_error.skip preserves the original error at tasks.X.error: a downstream task can branch on ${{ tasks.X.error.code }} while the status reads skipped.

The full error model

Retry policies, backoff strategies, recovery semantics, and the gate-based failure propagation rules. See spec/05-errors.md.