Skip to main content

Three channels

errors.mts
failing.nika is on the results page; list-notes.nika runs ls under permits: {}, see permits.

A refusal is not a run. The poster is the first screen of the recording: list-files.nika runs ls -1 under permits: {}, like list-notes.nika. check() returns the refusal (exit 2, NIKA-SEC-004) with its fix, and run() rejects with NikaOperationError, so no run, events or trace exist. Press play for the rest: the one-line fix, then an unsealed run, a sealed one and a tampered trace, which Receipts explains. Recorded in a terminal from @supernovae-st/nika 0.123.0 and its bundled engine nika 0.123.0 (0bfde3765); every model call is mock/echo, the engine’s offline rehearsal model, with no provider key and no network.

NikaOperationError

The engine refused an operation. Over the local transport:
  • code is the engine’s own: the first check finding that names one (NIKA-SEC-004, NIKA-PARSE-005, NIKA-AUTH-006…) or the refusal’s code (NIKA-1709, NIKA-1708). When the engine named none, as for an unreadable file or a cloud model the catalog cannot price (price unknown: …), code is the SDK’s run_refused.
  • findings holds the engine’s check findings untouched (code, message, severity, gate, kind, task). A budget or launch refusal has none.
  • status is the engine’s exit code: 2 for the file or its cost floor, 3 for the environment, the inputs or an unpriced cloud model.
  • operation names the refused call (run, check, compile…).
Over HTTP, a refusal the server types as { error: { code, message } } becomes a NikaOperationError whose status is the HTTP status (404 not found, 409 conflict, 412 stale schedule revision, 422 refused) and whose code is the server’s (not_found, idempotency_conflict, schedule_conflict, a stamped NIKA-… admission code). The artifact methods add theirs (job_not_settled, artifact_journal_unverified, artifact_changed, 403 artifact_too_large, 503 artifact_capacity…), with operation artifacts, downloadArtifact or readArtifact (Outputs and artifacts). Messages carry no paths, and a reflected bearer token is redacted. A frame or document larger than machineBufferBytes (16 MiB by default) is a NikaProtocolError whose message names the option and the size to set.

The error tree

Every error the SDK raises for an engine, transport, configuration or compatibility problem extends NikaError:
Misusing the API itself (an empty workflow name, a negative event cursor, a receipt that is not an object) throws a plain TypeError or RangeError before any engine or network work starts.
Over HTTP, traceVerify(receipt) can resolve verdict: "unavailable" when the server holds no journal for a job (refused before its first event, or still queued). That typed verdict is not a transport error and must not be converted into one.

Results

Every status an admitted run can end on.

Type index

Every exported result and error type.