Error Handling

Error Handling

Tooli provides structured error handling designed for agent self-correction. Errors include actionable suggestions that enable automatic recovery.

ToolError Hierarchy

ToolError (base)
├── InputError    — invalid arguments, missing input      → exit code 2
├── AuthError     — authentication/authorization failure  → exit code 30
├── StateError    — resource not found, conflict          → exit code 10
├── RuntimeError  — timeout, network failure              → exit code 70
└── InternalError — unexpected bugs                       → exit code 70

Error Fields

Field	Type	Description
code	str	Machine-readable code (e.g., "E3001")
category	ErrorCategory	One of: INPUT, AUTH, STATE, RUNTIME, INTERNAL
message	str	Human-readable error message
suggestion	Suggestion?	Actionable recovery hint
is_retryable	bool	Whether the operation can be retried
details	dict?	Additional context (traceback in verbose mode)

Suggestion Model

Suggestions guide agents toward self-correction:

from tooli.errors import StateError, Suggestion

raise StateError(
    message="Repository not found",
    code="E3001",
    suggestion=Suggestion(
        action="check",
        fix="Verify the repository name is correct",
        example="mytool list-repos",
        applicability="always"
    )
)

Field	Description
action	What kind of action to take: "check", "retry", "fix", "escalate"
fix	Human-readable description of the fix
example	Example command that might help
applicability	When this suggestion applies: "always", "sometimes", "if_interactive"

Exit Code Taxonomy

Code	Meaning	Error Category
0	Success	—
2	Input/usage error	INPUT
10	State error (not found, conflict)	STATE
20	Rate limited	RUNTIME
30	Auth error	AUTH
40	Permission denied	AUTH
50	Timeout	RUNTIME
65	Dependency not available	RUNTIME
70	Runtime/internal error	RUNTIME / INTERNAL
75	Temporary failure (retryable)	RUNTIME
101	Unknown/unhandled	INTERNAL

Error Output

JSON Mode (Non-TTY)

{
  "ok": false,
  "error": {
    "code": "E1001",
    "category": "input",
    "message": "Missing required argument: name",
    "is_retryable": false,
    "suggestion": {
      "action": "fix",
      "fix": "Provide the 'name' argument",
      "example": "mytool greet Alice"
    }
  },
  "meta": { "tool": "mytool.greet", "version": "1.0.0", "duration_ms": 1 }
}

Verbose Mode

With --verbose / -v, unexpected errors include the full traceback in error.details.traceback.

Click/Typer Errors

Click's built-in UsageError (e.g., missing arguments) is automatically mapped to exit code 2 with structured output.