iii-error-handling — Claude Code skill: handle SDK and engine errors
Skill teaches agents to read iii engine and SDK error codes, tell network failures from access denials, know when it is safe to retry. Use it when calling remote functions from Node, Python, Rust, or browser code.
npx skills add iii-hq/iii --skill iii-error-handling -a claude-codeWhat iii-error-handling does
iii emits two error classes: local (SDK, dispatcher) and remote (engine router, workers, RBAC). The skill shows how to branch on exact error code, not message string. For example, FORBIDDEN means policy denied — retrying is pointless, fix permissions instead. TIMEOUT from the SDK caller (Node/Python) means optimize or raise the timeout, not blind retry. invocation_error signals a routing or engine state issue — check the logs.
The skill lists error codes in a table with source, meaning, and typical handler. Observer errors are separate — they do not throw but land in the error channel or reject ready(). Examples cover Node (via InvocationError), Python (check exc.code), Rust (pattern match), and browser.
One constraint: messages over 16 MiB fail. Use a channel instead. For background work that must not drop, use a queue with retry and DLQ policy — documented in a separate pattern.
What it helps with
- Tell network timeout from permission denial and stop blindly retrying requests
- Diagnose
function_not_found— check function ID, worker status, or trigger type - Handle RBAC rejection and report it as permission error instead of looping
- Recode a message if it exceeds 16 MiB — when to switch to a channel
- Parse error codes from browser calls and remote worker responses
Example prompts for the agent
- Why does `orders::charge` return FORBIDDEN — is it policy or a bug in my call?
- How do I catch timeout in Python and tell it from other iii errors?
- What if my message is over 16 MiB — how do I use a channel instead of a direct call?
How to install iii-error-handling
1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-error-handling -a claude-code2Manually: put the files in place
~/.claude/skills/iii-error-handling/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/iii-error-handling/
1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-error-handling -a codex2Manually: put the files in place
.agents/skills/iii-error-handling/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-error-handling -a cursor2Manually: put the files in place
.cursor/skills/iii-error-handling/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install iii-hq/iii iii-error-handling2Manually: put the files in place
.github/skills/iii-error-handling/SKILL.md1Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-error-handling -a gemini-cli2Platform CLI
gemini skills install https://github.com/iii-hq/iii --path skills/iii-error-handlingManually: put the files in place
.devin/skills/iii-error-handling/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add iii-hq/iii --skill iii-error-handling -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
From the same set4
The whole set →Similar
Questions about iii-error-handling
How do I install iii-error-handling in Claude Code?
Run npx skills add iii-hq/iii --skill iii-error-handling -a claude-code. The skill will be at ~/.claude/skills/iii-error-handling/SKILL.md.
What does iii-error-handling do?
It explains how to read iii error codes (FORBIDDEN, TIMEOUT, function_not_found, etc.), which errors are safe to retry and which are not, and how to handle them in Node, Python, Rust, and the browser.
When should I retry a call and when should I not?
Retry network timeouts and connection failures only if the operation is idempotent. Never retry FORBIDDEN without fixing permissions. For reliable background work, use a queue with retry and DLQ policies.
