Error Handling

#Stable Error Metadata

Normalized runtime failures derive from DaitaError in daita.errors. Every normalized error carries:

• error_code: a stable snake-case identifier;
• retryability: unknown, transient, retryable, or permanent;
• retry_hint: the string form of retryability; and
• is_transient(), is_retryable(), and is_permanent() helpers.

from daita.errors import DaitaError
 
try:
    result = await agent.run("Summarize orders")
except DaitaError as error:
    logger.warning(
        "Daita failed",
        extra={
            "error_code": error.error_code,
            "retryability": error.retryability.value,
        },
    )
    if error.is_retryable():
        schedule_bounded_retry()
    else:
        raise

Do not decide retry behavior by parsing human-readable messages.

#Public Categories

Import these categories from daita.errors, not from provider or adapter internals.

#Input and Lifecycle Errors

Some public facade methods deliberately raise standard Python exceptions for programmer mistakes or exact lifecycle conditions. Examples include TypeError, ValueError, KeyError, and focused agent-home exceptions.

Treat these as corrections to input or lifecycle usage, not transient service failures:

from pathlib import Path
 
from daita import Agent, LocalWorkspace
from daita.agent import AgentNotFoundError
 
try:
    agent = await Agent.open(
        "missing-agent",
        workspace=LocalWorkspace(Path("/absolute/path/project")),
    )
except AgentNotFoundError:
    # Create the agent or correct the selected root/name.
    ...

Consult the method contract before adding a broad retry around agent creation, source mutation, or local knowledge mutation.

#Retry at the Narrow Boundary

Provider routing performs bounded retries and fallbacks only for normalized eligible model failures. Do not retry an entire run blindly: a completed tool call or approved local write may already have occurred before the terminal failure.

A safe application policy is:

1. log stable error metadata and the run ID when available;
2. retry only errors marked transient or retryable;
3. cap attempts and backoff time; and
4. inspect the persisted transcript before replaying a whole request.

Observer callbacks are different: their exceptions are intentionally swallowed and never fail the agent run.