Error taxonomy

Stable is the type. Message text is not a contract. Read ProjectionError.role / .where / .recipe instead of parsing the string.

Catch the owner, not the whole tree

The exception family tells the next responsible boundary what to do. Keep the typed error visible until the application can choose a code fix, a retry, a repair, or an operator response.

ap.AgentspartyError
├── ap.ProtocolError
│   ├── ap.ProjectionError        (.role, .where, .recipe)
│   ├── ap.ConformanceError
│   ├── ap.CompositionError
│   └── ap.ProtocolMismatch
├── ap.SessionError
│   ├── ap.AllowanceExceeded      (.limit, .spent)
│   ├── ap.SelectionError
│   ├── ap.DeadlineExceeded
│   ├── ap.JournalError
│   └── ap.Cancelled
├── ap.ContentError
│   ├── ap.DecodeError
│   └── ap.RefinementError
└── ap.ModelError
    ├── ap.ModelUnavailable
    └── ap.ModelRefused

Error	Stable contract
`AgentspartyError`	Base class for expected library boundary failures.
`ProtocolError`	The declared topology cannot be built or analysed.
`ProjectionError`	A role cannot observe or perform its projected duties.
`ConformanceError`	A participant does not conform to its endpoint.
`CompositionError`	Protocol fragments cannot be composed safely.
`ProtocolMismatch`	A journal belongs to another protocol shape.
`SessionError`	A running session cannot continue.
`AllowanceExceeded`	A run exceeded one named resource limit.
`SelectionError`	A participant selected a message outside its offer.
`DeadlineExceeded`	A declared time window expired before the step completed.
`JournalError`	Recorded decisions cannot be read or validated.
`Cancelled`	A participant received a session cancellation.
`ContentError`	A message value is invalid at the content boundary.
`DecodeError`	A response cannot be decoded into the offered message.
`RefinementError`	A decoded value fails a declared refinement.
`ModelError`	A model boundary failed to produce an answer.
`ModelUnavailable`	The provider or transport is unavailable.
`ModelRefused`	The provider refused the requested content.

import agentsparty as ap

tree = [
    ap.AgentspartyError,
    ap.ProtocolError,
    ap.ProjectionError,
    ap.ConformanceError,
    ap.CompositionError,
    ap.ProtocolMismatch,
    ap.SessionError,
    ap.AllowanceExceeded,
    ap.SelectionError,
    ap.DeadlineExceeded,
    ap.JournalError,
    ap.Cancelled,
    ap.ContentError,
    ap.DecodeError,
    ap.RefinementError,
    ap.ModelError,
    ap.ModelUnavailable,
    ap.ModelRefused,
]

ProtocolError covers malformed topology, projection, composition, and journal identity; SessionError covers runtime selection, budgets, cancellation, and deadlines. ContentError covers a payload that does not decode or satisfy a refinement. ModelError covers provider availability and refusal. A broken programmer contract is an assertion, not one of these expected boundary failures.

Handling strategy

Handle errors at the boundary that owns the next action:

Error family	Recovery belongs to	Typical response
`ProtocolError`	developer or deployment	fix the protocol, cast, or journal identity before accepting work
`SessionError`	application runtime	report a stopped run, ask for a human choice, or return a partial transcript
`ContentError`	participant boundary	repair a bounded decode failure or reject the input
`ModelError`	provider policy	retry when allowed, choose fallback, or surface the outage/refusal

Do not catch AgentspartyError at the top and turn every failure into “agent failed”. That loses whether the next action is a code change, a client retry, an operator decision, or a provider configuration fix. The exception type is the stable part of this API; message text is for diagnostics.

Projection and branch visibility: diagnose ProjectionError.
Sessions, execution, and limits: handle SessionError and AllowanceExceeded.
Roles, participants, and models: distinguish ModelUnavailable from ModelRefused.

Error taxonomy

Handling strategy

Related

On this page