Errors & Exceptions - mAIvn Docs

#Errors and exceptions

The SDK exposes a small exception hierarchy from maivn. Programming mistakes may also raise standard Python or Pydantic exceptions before a request is sent.

#Public SDK exceptions

Python

from maivn import (
    AsyncContextError,
    ConfigurationError,
    MaivnHTTPError,
    MaivnSDKError,
    ResourceRegistrationError,
    VaultSetupError,
)

Exception	Meaning
`MaivnSDKError`	Base class for SDK-owned failures.
`ConfigurationError`	Required SDK configuration is missing or invalid.
`VaultSetupError`	Automatic encrypted local storage could not open securely.
`AsyncContextError`	A synchronous facade was called from an active event loop; use its async sibling.
`ResourceRegistrationError`	A declared resource could not be registered or bound before invocation.
`MaivnHTTPError`	The mAIvn API returned a typed non-2xx response.

MaivnHTTPError provides status_code, reason, optional code, fields, retry_after, and detail attributes. error_code aliases code. It does not provide to_dict() or an automatic retry classifier.

#Error responses

Every non-2xx API response has one JSON shape:

JSON

{
  "detail": "Request validation failed.",
  "code": "validation_failed",
  "fields": [{"field": "messages.0.content", "message": "Field required"}]
}

Member	Always present	Meaning
`detail`	Yes	A message for a person. `MaivnHTTPError.reason` holds it.
`code`	Yes	A stable machine code, such as `not_found` or `plan_limit_exceeded`. Branch on this, not on `detail`.
`fields`	No	The request fields that failed validation, each with a message. `MaivnHTTPError.fields` holds them.
`retry_after`	No	Seconds to wait before retrying. The `Retry-After` header carries the same value.
`context`	No	Data specific to the code, such as the meter and reset time of a plan limit. `MaivnHTTPError.detail` holds it.

A plan-limit refusal raises PlanLimitExceededError, a MaivnHTTPError subclass whose meter, plan, limit, used, remaining, period_resets_at, and upgrade attributes come from context.

Python

from maivn import Agent, MaivnHTTPError, MaivnSDKError
from maivn.messages import HumanMessage

agent = Agent(name='assistant', api_key='your-api-key')

try:
    response = agent.invoke([HumanMessage(content='Summarize this ticket.')])
except MaivnHTTPError as exc:
    print(exc.status_code, exc.code, exc.reason)
    raise
except MaivnSDKError as exc:
    print(str(exc))
    raise

The root package also exports the parsing and resource errors used by current public APIs: SkillMarkdownError, SkillFrontmatterError, SkillCycleError, SkillChildNotFoundError, and ResourceRegistrationError.

#Validation and transport failures

Constructor, decorator, and option validation can raise ValueError, TypeError, or pydantic.ValidationError. These are deterministic input problems; correct the call rather than retrying it.

The SDK uses httpx for transport. Connection and timeout exceptions can therefore surface as httpx.HTTPError subclasses. Decide retry policy in your application from the concrete exception and operation; the SDK does not expose an is_retryable() helper.

Python

import httpx
from pydantic import ValidationError

try:
    response = agent.invoke('Summarize this ticket.')
except (TypeError, ValueError, ValidationError):
    raise  # fix input or configuration
except httpx.TimeoutException:
    raise  # apply application-specific backoff if this operation is safe to retry

#Invocation results

Successful invoke() and ainvoke() calls return maivn.InvokeResponse. The current model has no status or error field. It contains the final message, response, optional structured result, session/thread identifiers, event positions, usage metadata, stop reason, and tool-call summary. Interrupt and follow-up builders resolve checkpoints while consuming the stream; failures use exceptions or terminal stream events.

See Shared Data Models, Sessions and Streaming, and Interrupts.