tool-error-classify

Sort tool exceptions into a closed ErrorKind enum with LLM-friendly hint text. Zero deps.

from tool_error_classify import classify, ErrorKind

try:
    result = run_tool(...)
except Exception as exc:
    info = classify(exc)

    match info.kind:
        case ErrorKind.USER_INPUT:
            # bad args from the LLM — surface so it can correct itself
            return f"tool error: {info.hint}\n{exc}"
        case ErrorKind.RATE_LIMITED:
            back_off(seconds=info.retry_after_s or 5)
        case ErrorKind.RETRYABLE:
            retry()
        case ErrorKind.AUTH | ErrorKind.INTERNAL:
            raise  # not the LLM's problem

The closed enum:

Kind	Meaning	What to do
USER_INPUT	Bad args from LLM	Surface to model
AUTH	Auth failure	Stop, alert operator
NOT_FOUND	Missing resource	Tell LLM to try another
RATE_LIMITED	Throttled	Back off, retry
TIMEOUT	Request timed out	Smaller scope or wait
RETRYABLE	Transient	Retry with backoff
EXTERNAL_PERMANENT	External broken forever	Stop
INTERNAL	Our bug	Bubble up
UNKNOWN	Couldn't classify	Try once then give up

Why

The retry libs already exist. The fallback libs exist. The circuit breakers exist. What was missing was the decision layer: when a tool errors, which of those mechanisms should you invoke?

tool-error-classify is the one closed enum + a hint string per kind, so your agent loop can pattern-match on the result and route correctly.

What it inspects

In order:

1. A user-supplied custom_classifier(exc) -> ErrorKind | None (return None to defer)
2. exc.status_code or exc.response.status_code (covers httpx, anthropic, openai, requests, etc.)
3. Native TimeoutError / ConnectionError / OSError
4. The exception class name against a built-in keyword list (RateLimit, Throttling, Timeout, Unauthorized, Authentication, PermissionDenied, Forbidden, NotFound, DoesNotExist, Overloaded, ServiceUnavailable, APIConnection, InternalServer, ServiceQuotaExceeded, Validation, InvalidArgument, BadRequest)
5. Built-in Python ValueError / TypeError / KeyError / IndexError / AssertionError / AttributeError / LookupError → USER_INPUT
6. Fallback: UNKNOWN

Retry-After header values (numeric seconds) on the response are extracted into ClassifiedError.retry_after_s when present.

Install

pip install tool-error-classify

API

from tool_error_classify import (
    classify,           # main entrypoint
    ErrorKind,          # closed Enum (str-based, JSON-friendly)
    ClassifiedError,    # frozen dataclass result
    DEFAULT_HINTS,      # per-kind default hint strings
)

ClassifiedError(
    kind: ErrorKind,
    hint: str,
    status_code: int | None,
    retry_after_s: float | None,
)

classify(
    exc,
    custom_classifier=None,   # Callable[[BaseException], ErrorKind | None]
    hints=None,               # dict[ErrorKind, str] override
) -> ClassifiedError

Companion libraries

• llm-retry — once you know the error is RETRYABLE or RATE_LIMITED, this handles the backoff.
• llm-circuit-breaker — wire ErrorKind.RETRYABLE count to the breaker's failure threshold.
• llm-fallback-router — EXTERNAL_PERMANENT for provider A means try provider B.

License

MIT