Errors

CharterError
├── DeclarationError     a schema or pack is declared in an unusable shape
├── CredentialError      credentials missing, expired, or rejected
│   └── InsufficientScope  the grant does not cover this call
├── ToolValidationError  the arguments did not satisfy the schema
├── TransformError       a Format transform could not resolve or run
├── APIError             the upstream API returned a non-success
└── NetworkError         the connection failed, dropped or timed out

class CharterError(Exception):
    docs: Optional[str]

    @property
    def docs_url(self) -> Optional[str]: ...

from charter import CharterError

try:
    ...
except CharterError as exc:
    ...

class DeclarationError(CharterError, ValueError): ...

from charter import DeclarationError, Pagination

try:
    Pagination(cursor_field="next_page_token", page_param="page")
except DeclarationError as exc:
    print(exc)
    # A Pagination declares one style, not both: cursor (cursor_field/
    # cursor_param) or page number (page_param/per_page_param).
    # See https://docs.r28.ai/charter/reference/envelopes-and-pagination#pagination

class CredentialError(CharterError):
    def __init__(
        self,
        message: str,
        *,
        provider: Optional[str] = None,
        status_code: Optional[int] = None,
        token_refused: Optional[bool] = None,
        reauthorize: bool = False,
    ) -> None: ...

class InsufficientScope(CredentialError):
    def __init__(
        self,
        message: str,
        *,
        provider: Optional[str] = None,
        status_code: Optional[int] = 403,
        needed: Sequence[str] = (),
        accepted: Sequence[str] = (),
        kind: Optional[Kind] = None,
    ) -> None: ...

class ToolValidationError(CharterError):
    def __init__(
        self,
        message: str,
        *,
        tool_name: Optional[str] = None,
        errors: Optional[list[dict[str, Any]]] = None,
    ) -> None: ...

class ContextError(CharterError):
    def __init__(self, message: str, *, tool_name: str, field: str, key: str) -> None: ...

class TransformError(CharterError):
    def __init__(
        self,
        message: str,
        *,
        transform: Optional[str] = None,
        field: Optional[str] = None,
    ) -> None: ...

class APIError(CharterError):
    def __init__(
        self,
        message: str,
        *,
        status_code: int,
        body: str = "",
        url: Optional[str] = None,
        retry_after: Optional[int] = None,
    ) -> None: ...

import asyncio

from charter import APIError


async def main():
    try:
        ...
    except APIError as exc:
        if exc.retry_after:
            await asyncio.sleep(exc.retry_after)


asyncio.run(main())

class NetworkError(CharterError):
    def __init__(
        self,
        message: str,
        *,
        url: Optional[str] = None,
        host: Optional[str] = None,
        may_have_taken_effect: bool = True,
    ) -> None: ...

Could not reach graph.microsoft.com (timed out connecting). The request was never
sent, so nothing changed. This is a network problem on the tool's side, not a
problem with the arguments; the same call may work later.

No response from graph.microsoft.com (timed out waiting for the response). The
request may have reached the server and taken effect, so check before repeating
anything that changes data. This is a network problem on the tool's side, not a
problem with the arguments.

from charter import (
    APIError,
    ContextError,
    CredentialError,
    InsufficientScope,
    NetworkError,
    ToolValidationError,
)

try:
    ...
except ToolValidationError as exc:
    handled = f"tell the model: {exc}"
except ContextError as exc:
    handled = f"fix the application: pass {exc.key!r} in context"
except InsufficientScope as exc:
    handled = f"ask {exc.provider} for {exc.needed}"
except CredentialError as exc:
    handled = f"re-authorize {exc.provider}"
except APIError as exc:
    handled = f"upstream said {exc.status_code}"
except NetworkError as exc:
    handled = "safe to retry" if not exc.may_have_taken_effect else "check first"

import logging

from charter import CharterError
from charter.types.errors import unexpected_failure_text


async def call(tool, args):
    try:
        return await tool.ainvoke(args)
    except CharterError as exc:
        return str(exc)
    except Exception as exc:
        logging.getLogger("charter").exception("tool %s failed", tool.name)
        return unexpected_failure_text(tool.name, exc)