iii-error-handling

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.

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.