runtime · failure model
Keep refusals typed.
Separate file findings, workflow failure, environment failure, cancellation and remote transport errors.
One catch-all error handler erases the distinction between a file that was refused, a run that failed and infrastructure that disappeared. Keep those branches visible.
Do not catch a dirty file.
check resolves even when findings exist. This makes a complete diagnostic list available to editors, CI and applications.
const report = await nika.check(file)
if (!report.clean) {
return { accepted: false, findings: report.findings }
}Preserve the engine exit contract.
The outcome tells you whether the graph completed and why it did not. Do not flatten all non-zero exits into a generic exception.
0 completed 1 workflow failed 2 findings or refusal 3 environment 4 paused
Narrow the client hierarchy.
The preview HTTP client exposes API, connection, timeout, job and cancellation classes. Catch the narrowest class that changes product behavior.
try {
await remote.jobs.run('release.nika.yaml')
} catch (error) {
if (error instanceof NikaJobCancelledError) return 'cancelled'
if (error instanceof NikaJobError) return 'failed'
if (error instanceof NikaTimeoutError) return 'timed-out'
throw error
}