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.
Security Assessment
About iii-error-handling
This skill is a reference guide for handling errors from the iii engine and its SDKs across Node, Python, Rust, and browser workers. It solves the problem of correctly interpreting and reacting to failures in a distributed invocation system by teaching agents to branch on exact error `code` strings rather than matching message text, and by keeping engine wire codes separate from SDK-local codes.
The core content is a table of error codes with their emitter, meaning, and recommended handling, spanning function_not_found, invocation_error, invocation_stopped, FORBIDDEN (RBAC denial), lowercase and uppercase timeout variants, function_not_invokable, and invocation_failed. It distinguishes handler errors (user function code, SDK local dispatch, HTTP-invoked endpoints) from engine errors (routing, invocation state, RBAC, protocol, worker wire errors), and gives retryability rules: retry transient timeouts and transport failures only for idempotent operations, never retry FORBIDDEN without changing auth or policy, and never retry function_not_found by calling the same ID. It provides idiomatic exception-handling snippets for each SDK surface and points to sibling skills for invocation modes, SDK exception classes, and workflow-level retry and DLQ design.
Target users are developers building on the iii platform who need to interpret error codes, decide retry behavior, handle RBAC denials and timeouts, or map errors to SDK-specific exception classes. It is a single SKILL.md documentation reference with no executable tooling. Typical use cases include writing robust error branches, diagnosing failed invocations, and choosing between synchronous handling and enqueued background work.
FAQ
What should agents branch on when handling iii errors?
On the exact error code string rather than message text, and the skill stresses keeping engine wire codes separate from SDK-local codes since some codes (like timeout) appear in both lowercase and uppercase forms with different origins.
Which SDK languages are covered?
Node (TypeScript), Python, Rust, and browser workers, each with an idiomatic error-handling example, including catching InvocationError and matching codes such as FORBIDDEN.
When is it safe to retry?
Only for transient timeout, transport, or worker-reconnect failures and only when the operation is idempotent. FORBIDDEN should not be retried without changing auth or policy, and function_not_found should not be retried by re-calling the same ID.
How does it distinguish handler errors from engine errors?
Handler errors originate in user function code, SDK local dispatch, or HTTP-invoked endpoints, while engine errors come from routing, invocation state, RBAC, protocol handling, or worker-reported wire errors.
What about reliable background work?
It recommends using TriggerAction.Enqueue with a queue and queue retry/DLQ policy for reliable background work, noting that queue retries only apply to enqueued work while synchronous failures return directly to the caller.
Install iii-error-handling
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
iii-hq/iii