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.
Error Codes
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 |
Handler vs Engine Errors
- Handler errors originate in user function code, SDK local dispatch, or HTTP-invoked endpoints.
- Engine errors originate in routing, invocation state, RBAC, protocol handling, or worker-reported wire errors.
- Queue retries only apply to enqueued work. Synchronous failures are returned directly to the caller.
- Void dispatch does not return handler results, so use logs/observability for failures.
Retryability
- Retry transient
timeout, TIMEOUT, transport, or worker reconnect failures only when the operation is idempotent.
- Do not retry
FORBIDDEN without changing auth/policy.
- Do not retry
function_not_found by calling the same ID repeatedly; discover functions or install/start the missing worker.
- For reliable background work, use
TriggerAction.Enqueue({ queue }) and queue retry/DLQ policy.
SDK Surfaces
Node
import { InvocationError } from 'iii-sdk'
try {
await iii.trigger({ function_id: 'orders::charge', payload })
} catch (error) {
if (error instanceof InvocationError && error.code === 'FORBIDDEN') {
throw new Error('Policy denied orders::charge')
}
throw error
}
Python
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}")
Rust
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()),
}
Browser
Browser trigger calls reject with JavaScript errors. Preserve the engine-provided code/message when present and show policy failures as permission errors in UI.
Pattern Boundaries
- For invocation modes and enqueue decisions, prefer
iii-core-primitives.
- For SDK-specific exception classes and syntax, prefer
iii-sdk-reference.
- For workflow-level retry and DLQ design, prefer
iii-architecture-patterns.
- For RBAC policy design and logs/traces around worker failures, use the matching worker docs under
engine/src/workers/**/skills.
When to Use
- Use this skill when the task mentions iii errors, exception handling, failed invocations, timeouts, forbidden calls, retry behavior, or SDK error classes.
Boundaries
- Do not retry non-idempotent work automatically unless it is enqueued under queue policy.
- Do not treat RBAC denial as a missing worker.
- Do not generate removed service APIs or adapter-extension APIs.
1---2name: iii-error-handling3description: 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.4---5
6# Error Handling
7
8iii 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.
9
10## Error Codes
11
12Branch on exact `code` strings, but keep engine wire codes separate from SDK-local codes.
13
14| Code | Emitted by | Meaning | Typical handling |
15| --- | --- | --- | --- |
16| `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 |
17| `invocation_error` | Engine invocation/router path | Engine failed to route, remember, or complete the invocation | Inspect engine logs, protocol state, and worker connectivity |
18| `invocation_stopped` | Engine invocation handler | Invocation was cancelled or stopped by the engine/runtime | Treat as failed work; decide whether caller should retry |
19| `FORBIDDEN` | RBAC / worker-gated engine functions | RBAC denied the action | Do not retry blindly; inspect policy, auth context, and allowed functions |
20| `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 |
21| `function_not_invokable` | SDK local dispatch | Registration exists but cannot be invoked as a normal local function | Inspect registration/invocation type |
22| `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 |
23| `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 |
24
25## Handler vs Engine Errors
26
27- Handler errors originate in user function code, SDK local dispatch, or HTTP-invoked endpoints.
28- Engine errors originate in routing, invocation state, RBAC, protocol handling, or worker-reported wire errors.
29- Queue retries only apply to enqueued work. Synchronous failures are returned directly to the caller.
30- Void dispatch does not return handler results, so use logs/observability for failures.
31
32## Retryability
33
34- Retry transient `timeout`, `TIMEOUT`, transport, or worker reconnect failures only when the operation is idempotent.
35- Do not retry `FORBIDDEN` without changing auth/policy.
36- Do not retry `function_not_found` by calling the same ID repeatedly; discover functions or install/start the missing worker.
37- For reliable background work, use `TriggerAction.Enqueue({ queue })` and queue retry/DLQ policy.
38
39## SDK Surfaces
40
41### Node
42
43```typescript
44import { InvocationError } from 'iii-sdk'
45
46try {
47 await iii.trigger({ function_id: 'orders::charge', payload })
48} catch (error) {
49 if (error instanceof InvocationError && error.code === 'FORBIDDEN') {
50 throw new Error('Policy denied orders::charge')
51 }
52 throw error
53}
54```
55
56### Python
57
58```python
59from iii import InvocationError
60
61try:
62 result = iii.trigger({"function_id": "orders::charge", "payload": payload})
63except InvocationError as exc:
64 if exc.code == "FORBIDDEN":
65 raise RuntimeError("Policy denied orders::charge")
66 if exc.code in ("TIMEOUT", "timeout"):
67 raise RuntimeError("orders::charge timed out")
68 raise RuntimeError(f"{exc.code}: {exc.message}")
69```
70
71### Rust
72
73```rust
74match iii.trigger(request).await {
75 Ok(value) => value,
76 Err(iii_sdk::Error::Timeout) => {
77 return Err("orders::charge timed out".into());
78 }
79 Err(iii_sdk::Error::Remote { code, message, .. }) if code == "FORBIDDEN" => {
80 return Err(format!("policy denied: {message}").into());
81 }
82 Err(err) => return Err(err.into()),
83}
84```
85
86### Browser
87
88Browser trigger calls reject with JavaScript errors. Preserve the engine-provided code/message when present and show policy failures as permission errors in UI.
89
90## Pattern Boundaries
91
92- For invocation modes and enqueue decisions, prefer `iii-core-primitives`.
93- For SDK-specific exception classes and syntax, prefer `iii-sdk-reference`.
94- For workflow-level retry and DLQ design, prefer `iii-architecture-patterns`.
95- For RBAC policy design and logs/traces around worker failures, use the matching worker docs under `engine/src/workers/**/skills`.
96
97## When to Use
98
99- Use this skill when the task mentions iii errors, exception handling, failed invocations, timeouts, forbidden calls, retry behavior, or SDK error classes.
100
101## Boundaries
102
103- Do not retry non-idempotent work automatically unless it is enqueued under queue policy.
104- Do not treat RBAC denial as a missing worker.
105- Do not generate removed service APIs or adapter-extension APIs.
om-scogo