Skip to content

errors

errors

Error classification for managed agent execution.

Classes

AgentTickError

Bases: Exception

Base class for agent tick errors.

RetryableError

Bases: AgentTickError

Transient error that should be retried with backoff.

FatalError

Bases: AgentTickError

Permanent error that requires user intervention.

EscalateError

Bases: AgentTickError

Agent is uncertain and needs human input.

Functions

classify_error 

classify_error(exc: Exception) -> AgentTickError

Classify an arbitrary exception into a RetryableError or FatalError.

Source code in src/openjarvis/agents/errors.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def classify_error(exc: Exception) -> AgentTickError:
    """Classify an arbitrary exception into a RetryableError or FatalError."""
    if isinstance(exc, AgentTickError):
        return exc

    msg = str(exc).lower()

    # Check fatal patterns first (more specific)
    if isinstance(exc, PermissionError):
        return FatalError(str(exc))
    for pattern in _FATAL_PATTERNS:
        if pattern in msg:
            return FatalError(str(exc))

    # Check retryable patterns
    if isinstance(exc, (TimeoutError, ConnectionError, OSError)):
        return RetryableError(str(exc))
    for pattern in _RETRYABLE_PATTERNS:
        if pattern in msg:
            return RetryableError(str(exc))

    # Default: assume retryable (better to retry than to give up)
    return RetryableError(str(exc))

retry_delay 

retry_delay(attempt: int) -> int

Exponential backoff delay in seconds: min(10 * 2^attempt, 300).

Source code in src/openjarvis/agents/errors.py 
85
86
87
def retry_delay(attempt: int) -> int:
    """Exponential backoff delay in seconds: min(10 * 2^attempt, 300)."""
    return min(10 * (2**attempt), 300)

suggest_action 

suggest_action(error: AgentTickError) -> str

Return a human-readable suggested action for the given error.

Source code in src/openjarvis/agents/errors.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def suggest_action(error: AgentTickError) -> str:
    """Return a human-readable suggested action for the given error."""
    msg = str(error).lower()
    if any(p in msg for p in ("rate limit", "rate_limit", "429", "too many requests")):
        return "Rate limited \u2014 agent will auto-retry on next tick"
    if any(p in msg for p in ("timeout", "timed out", "connection", "unavailable")):
        return "Engine not reachable \u2014 check that your inference engine is running"
    if any(p in msg for p in ("401", "403", "permission", "unauthorized", "api key")):
        return "Check API key configuration in Settings"
    if "not found" in msg or "404" in msg:
        return "Model or endpoint not found \u2014 verify model name and engine URL"
    return "Unexpected error \u2014 check the full trace for details"