OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add iii-hq/iii --skill iii-error-handling
Handle iii engine and SDK errors across Node, Python, Rust, and browser workers. Use when interpreting error codes, retryability, RBAC denial, timeouts, handler failures, or SDK-specific exception surfaces.
npx skills add iii-hq/iii --skill iii-error-handling
iii has two broad error classes: SDK/local errors and engine/remote invocation errors. Agents should branch on the error code instead of matching only message strings.
Branch on exact code strings, but keep engine wire codes separate from SDK-local codes.
| Code | Emitted by | Meaning | Typical handling |
|---|---|---|---|
function_not_found | Engine and SDK local dispatch | No registered function is available under that ID | Check function ID, worker install/startup, discovery, and trigger type hints |
invocation_error | Engine invocation/router path | Engine failed to route, remember, or complete the invocation | Inspect engine logs, protocol state, and worker connectivity |
invocation_stopped | Engine invocation handler | Invocation was cancelled or stopped by the engine/runtime | Treat as failed work; decide whether caller should retry |
FORBIDDEN | RBAC / worker-gated engine functions | RBAC denied the action | Do not retry blindly; inspect policy, auth context, and allowed functions |
timeout | Engine/worker wire error when a worker reports lowercase timeout | Invocation exceeded a timeout reported through the wire protocol | Treat as timeout, but do not assume every SDK maps it to a timeout subclass |
function_not_invokable | SDK local dispatch | Registration exists but cannot be invoked as a normal local function | Inspect registration/invocation type |
invocation_failed | SDK worker handler wrappers | Local worker handler, HTTP-invoked function wrapper, or SDK-side handler path failed | Inspect handler logs, stacktrace, and payload validation |
TIMEOUT | Node/Python SDK caller timeout | Client waited longer than trigger() timeout | Increase timeout only if the workload is expected to run long; otherwise optimize or enqueue |
timeout, TIMEOUT, transport, or worker reconnect failures only when the operation is idempotent.FORBIDDEN without changing auth/policy.function_not_found by calling the same ID repeatedly; discover functions or install/start the missing worker.TriggerAction.Enqueue({ queue }) and queue retry/DLQ policy.Browser trigger calls reject with JavaScript errors. Preserve the engine-provided code/message when present and show policy failures as permission errors in UI.
iii-core-primitives.iii-sdk-reference.iii-architecture-patterns.engine/src/workers/**/skills.from iii import InvocationError
try:
result = iii.trigger({"function_id": "orders::charge", "payload": payload})
except InvocationError as exc:
if exc.code == "FORBIDDEN":
raise RuntimeError("Policy denied orders::charge")
if exc.code in ("TIMEOUT", "timeout"):
raise RuntimeError("orders::charge timed out")
raise RuntimeError(f"{exc.code}: {exc.message}")match iii.trigger(request).await {
Ok(value) => value,
Err(iii_sdk::Error::Timeout) => {
return Err("orders::charge timed out".into());
}
Err(iii_sdk::Error::Remote { code, message, .. }) if code == "FORBIDDEN" => {
return Err(format!("policy denied: {message}").into());
}
Err(err) => return Err(err.into()),
}