The Result-Based Error Model
This explains why the SDK never throws, what a Result is, and how to read a LiganticError.
Why the SDK Never Throws
A fallible SDK operation returns a value that is the outcome, rather than signaling failure by throwing.
The reasons:
- Failures are data. A network error or a
404is an expected, handleable outcome — not an exceptional one. Returning it lets you branch on it cleanly withouttry/catch. - One shape everywhere. Every operation returns the same
Promise<LiganticResult<T>>, so the handling code is uniform across the whole SDK. - No accidental swallowing. Because the SDK doesn't throw, there is no
try/catchscope where a failure can be silently ignored. You must inspect.ok. - The CLI renders it. The CLI's clean
error: ...output is theErrside of the same result, rendered for a human.
The Result Type
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
type LiganticResult<T> = Result<T, LiganticError>;Every operation returns Promise<LiganticResult<T>>. You check the ok flag:
const schema = await client.schemas.get(spaceId, schemaId);
if (schema.ok) {
// schema.value is typed as Schema
} else {
// schema.error is a LiganticError
}Helpers are exported for convenience:
ok(value)/err(error)— construct each side.tryOr(fn, toError)— run a function and capture any thrown error as theErrside. This is the boundary where an unexpected exception (for example an aborted fetch) becomes aLiganticError.
Reading a LiganticError
LiganticError mirrors the API's documented error envelope { message, code, issues? } and adds transport context:
Field | Meaning |
|---|---|
| Human-readable description. |
| HTTP status, or |
| The API error code, for example, |
| Validation issues, present for |
| The |
|
|
|
|
A few examples:
// API returned 404.
error.status; // 404
error.code; // "NOT_FOUND"
error.message; // "..."
// The request never reached the server.
error.status; // null
error.code; // "NETWORK_ERROR"
error.isTransportError; // trueHow This Interacts with Retries
The retry policy is keyed off isRetryable:
- A
429is always auto-retried, for any method — the server rejects it before the handler runs, so retrying is safe even forPOSTandPATCH. - Other retryable failures (a transport failure, or a
408/5xx) are retried only for idempotent requests:GET,DELETE, andPUT. - A non-idempotent
408/5xxis surfaced immediately as anErrresult so you can decide what to do.
When a 429 carries a Retry-After header, the SDK waits at least that long before retrying (capped by maxRetryAfterMs, default 60 s), so the wait matches the server's rate-limit window instead of the short default backoff.
So by the time you inspect a result, any retryable failure has already been retried up to the configured maxRetries.
Handling a Failed Result
const result = await client.flows.run(spaceId, flowId, { inputs });
if (!result.ok) {
const e = result.error;
// Log or surface. Include e.requestId for support.
throw new Error(`${e.code}: ${e.message}${e.requestId ? ` (request ${e.requestId})` : ""}`);
}
const runId = result.value.flowExecutionId;For the CLI, you don't write this at all — the CLI renders the Err side as error: <message> on stderr and exits non-zero.