The public exception hierarchy Dendrux raises, when each fires, the constructor arguments, and a suggested HTTP status mapping for your write routes.

Errors

Dendrux's runtime methods raise typed exceptions on precondition failures. You catch them in your own routes (or CLI, or jobs) and map them to status codes. Dendrux never forces a status-code contract.

from dendrux.errors import (
    RunNotFoundError, RunNotPausedError, PauseStatusMismatchError,
    RunAlreadyClaimedError, RunAlreadyTerminalError, InvalidToolResultError,
    PersistenceNotConfiguredError, SchemaNotInitializedError, SchemaOutOfDateError,
    SkillValidationError, SkillMissingError, SkillMismatchError,
    ContextLengthExceededError,
    ImageError, InvalidImageError, ImageLimitError, ImageFetchError, UnsupportedModalityError,
    ImageRejectedError, ProviderError, BlobNotFoundError, BlobIntegrityError,
    ImagePersistenceUnsupportedError, BlobContentionError,
)

The most common ones are also re-exported from the top-level dendrux package.

The hierarchy

None of the image errors contain image bytes, base64 or a URL's query string, and they are raised without a chained exception. Each carries its arguments as attributes (err.run_id, err.current_status, etc.) for structured handling. ContextLengthExceededError carries err.status_code, err.provider_code and err.model. SkillMissingError and SkillMismatchError share the base class SkillContinuityError (a RuntimeError) and expose err.missing and err.mismatched; see the resume contract.

Also exported from dendrux

A few related exceptions live on the package root rather than dendrux.errors:

Errors raised by the new run-control methods

The 0.3.0 methods reuse the hierarchy above. These are the cases worth knowing:

MCP errors

MCP tool sources raise their own typed hierarchy under MCPError, importable from dendrux.mcp. The ones an application should be ready to handle — including MCPCircuitOpenError (fail-fast with retry_after), the capacity errors, and MCPOutcomeUnknownError (interrupted call the server may have applied; never retry automatically) — are tabulated with their semantics on the MCP page.

Example: mapping errors in a write route

from fastapi import APIRouter, Depends, HTTPException
from dendrux.errors import (
    PauseStatusMismatchError, PersistenceNotConfiguredError,
    RunAlreadyClaimedError, RunAlreadyTerminalError,
    RunNotFoundError, RunNotPausedError,
)
 
@router.post("/runs/{run_id}/approval")
async def approval_route(run_id: str, body: dict, _=Depends(authorize)):
    try:
        result = await agent.submit_approval(
            run_id, approved=body["approved"], rejection_reason=body.get("rejection_reason"),
        )
    except RunNotFoundError:
        raise HTTPException(404, "run not found")
    except (RunNotPausedError, PauseStatusMismatchError,
            RunAlreadyClaimedError, RunAlreadyTerminalError) as e:
        raise HTTPException(409, str(e))
    except PersistenceNotConfiguredError:
        raise HTTPException(500, "persistence not configured")
    return {"status": result.status.value, "answer": result.answer}

Where this fits

• Agent: which method raises which error.
• Human-in-the-loop approval and Cancelling a run: error handling in context.