Errors

Every error the SDK raises, from guardian_agent.errors, and proxy_error, which recovers the SDK's error from a model client's.

View as Markdown

Every error the SDK raises derives from GuardianAgentError, and each is also importable from guardian_agent. A refusal that reaches you through a model client’s own error can be recovered with proxy_error.

proxy_error

`proxy_error`

python

proxy_error(source: object) -> GuardianAgentError | None

The SDK’s error for a refusal, from a response or an error that holds one.

Parameters:

source (object) – An httpx or httpx2 response, or an exception with a response attribute, such as openai.APIStatusError.

Returns:

GuardianAgentError | None – The refusal as this SDK’s typed error, with the proxy’s code, message, hint and status; or None when it isn’t one (the provider’s own error, say). It never raises.

guardian_agent.errors

Every error the SDK raises.

All of them derive from GuardianAgentError, and each carries the stable code the contract defines (the same code the proxy sends), a message for people, an optional hint saying what to do, and the HTTP status when the error came from the proxy. Branch on the class or on code; message may change between releases.

Errors are grouped so you can catch a whole family:

python

try:
    agent.register()
except ga.DefinitionError as error:      # anything wrong with the definition
    ...
except ga.ProxyError as error:           # the proxy is down, old, or refusing
    ...

A model client routed with Agent.bind() raises its own errors, so its retries keep working; guardian_agent.proxy_error turns a refusal back into one of these:

python

try:
    client.chat.completions.create(...)
except openai.APIStatusError as error:
    if refusal := ga.proxy_error(error):
        ...

No error ever repeats a value you submitted, which may be a credential: they name where a problem is and which rule it breaks.

Classes:

GuardianAgentError – The base of every error the SDK raises.
ProxyError – The local Viper proxy can’t be used: down, incompatible or refusing.
ProxyUnreachable – Nothing answered at the proxy’s address, or it didn’t answer in time.
ProxyIncompatible – The proxy lacks the agent API, definition schema or features this SDK uses.
NotLocal – The proxy refused the call because it didn’t come from this machine.
NotFound – The proxy has no such endpoint; usually a proxy older than the SDK.
MethodNotAllowed – The endpoint exists but not for that method; a version mismatch.
ProxyInternalError – The proxy failed in a way the caller can’t fix; its log says why.
UpstreamUnreachable – The proxy couldn’t reach the gateway, so nothing was sent.
RequestUnreadable – The proxy couldn’t take in the request’s body.
UpstreamResponseLost – The request was sent, but no complete answer came back.
UnexpectedResponse – The proxy answered with something this SDK can’t read.
DefinitionError – The agent definition breaks a rule; nothing was registered.
DefinitionInvalid – The definition breaks the schema or a validation rule.
DefinitionTooLarge – The definition, or part of it, is over one of the proxy’s limits.
DefinitionContainsSecret – The definition looks like it holds a credential, which is never recorded.
SchemaVersionUnsupported – The proxy doesn’t accept this definition schema version.
CollectionInvalid – A skill’s or memory source’s files can’t be stored as given; none were.
CollectionTooLarge – A skill’s or memory source’s files are over one of the proxy’s limits.
AgentError – The proxy couldn’t match a request to an enrolled agent and definition.
AgentHeaderRequired – The proxy only signs requests that name an agent, and this one didn’t.
AgentHeaderInvalid – An agent header was repeated, empty or not text.
AgentNotEnrolled – No agent of that name is enrolled on this proxy.
DefinitionUnknown – The definition isn’t registered for this agent on the proxy.
SubagentUnknown – The definition has no sub-agent of that name.
SigningFailed – The proxy couldn’t sign the request, so it didn’t forward it.
ModelNotRoutedThroughProxy – A model client points somewhere other than the proxy, so it would go unsigned.
UnrecognisedError – An error with a code this SDK doesn’t know, from a newer proxy.

`errors.GuardianAgentError`

python

GuardianAgentError(message: str, *, hint: str | None = None, status: int | None = None)

Bases: Exception

The base of every error the SDK raises.

Attributes:

code (str) – The contract’s error code, such as "agent_not_enrolled".
message – What went wrong, for people.
hint – What to do about it, when there is something to do.
status – The HTTP status the proxy answered with, if it answered.

Parameters:

message (str) – What went wrong.
hint (str | None) – What to do about it.
status (int | None) – The proxy’s HTTP status, if the error came from the proxy.

`errors.GuardianAgentError.code`

python

code: str = 'guardian_agent_error'

The contract’s error code; each subclass sets its own.

`errors.ProxyError`

Bases: GuardianAgentError

The local Viper proxy can’t be used: down, incompatible or refusing.

`errors.ProxyUnreachable`

Bases: ProxyError

Nothing answered at the proxy’s address, or it didn’t answer in time.

`errors.ProxyIncompatible`

Bases: ProxyError

The proxy lacks the agent API, definition schema or features this SDK uses.

`errors.NotLocal`

Bases: ProxyError

The proxy refused the call because it didn’t come from this machine.

`errors.NotFound`

Bases: ProxyError

The proxy has no such endpoint; usually a proxy older than the SDK.

`errors.MethodNotAllowed`

Bases: ProxyError

The endpoint exists but not for that method; a version mismatch.

`errors.ProxyInternalError`

Bases: ProxyError

The proxy failed in a way the caller can’t fix; its log says why.

`errors.UpstreamUnreachable`

Bases: ProxyError

The proxy couldn’t reach the gateway, so nothing was sent.

Retrying may help, and model clients retry it. The hint says what to check.

`errors.RequestUnreadable`

Bases: ProxyError

The proxy couldn’t take in the request’s body.

It broke off on the way in (send it again), or was over the relay limit (send less). Not retried for you.

`errors.UpstreamResponseLost`

Bases: ProxyError

The request was sent, but no complete answer came back.

The connection failed while waiting, or the answer couldn’t be read or passed on. The model may have run, so this isn’t retried for you: check before sending the request again.

`errors.UnexpectedResponse`

Bases: ProxyError

The proxy answered with something this SDK can’t read.

Its body is never repeated in the message. Raised for a body that isn’t JSON, or isn’t the shape the agent API defines.

`errors.DefinitionError`

python

DefinitionError(message: str, *, problems: Iterable[Problem] = (), hint: str | None = None, status: int | None = None)

Bases: GuardianAgentError

The agent definition breaks a rule; nothing was registered.

Attributes:

problems (tuple[Problem, ...]) – Where the definition breaks which rule, when that’s known: always for a definition checked locally, never for one the proxy refused (its message says where).

Parameters:

message (str) – What went wrong.
problems (Iterable[Problem]) – Where the definition breaks which rule.
hint (str | None) – What to do about it.
status (int | None) – The proxy’s HTTP status, if the proxy refused it.

`errors.DefinitionInvalid`

Bases: DefinitionError

The definition breaks the schema or a validation rule.

`errors.DefinitionTooLarge`

Bases: DefinitionError

The definition, or part of it, is over one of the proxy’s limits.

`errors.DefinitionContainsSecret`

Bases: DefinitionError

The definition looks like it holds a credential, which is never recorded.

Checked locally, problems names each place, as rule secret with what it looks like as kind; the value is never repeated.

`errors.SchemaVersionUnsupported`

Bases: DefinitionError

The proxy doesn’t accept this definition schema version.

`errors.CollectionInvalid`

Bases: DefinitionError

A skill’s or memory source’s files can’t be stored as given; none were.

`errors.CollectionTooLarge`

Bases: DefinitionError

A skill’s or memory source’s files are over one of the proxy’s limits.

`errors.AgentError`

Bases: GuardianAgentError

The proxy couldn’t match a request to an enrolled agent and definition.

`errors.AgentHeaderRequired`

Bases: AgentError

The proxy only signs requests that name an agent, and this one didn’t.

`errors.AgentHeaderInvalid`

Bases: AgentError

An agent header was repeated, empty or not text.

`errors.AgentNotEnrolled`

Bases: AgentError

No agent of that name is enrolled on this proxy.

The proxy reads its agents when it starts, so an agent enrolled since then needs the proxy restarted.

`errors.DefinitionUnknown`

Bases: AgentError

The definition isn’t registered for this agent on the proxy.

The proxy remembers registrations only while it runs, so this usually follows a proxy restart.

`errors.SubagentUnknown`

Bases: AgentError

The definition has no sub-agent of that name.

`errors.SigningFailed`

Bases: GuardianAgentError

The proxy couldn’t sign the request, so it didn’t forward it.

`errors.ModelNotRoutedThroughProxy`

Bases: GuardianAgentError

A model client points somewhere other than the proxy, so it would go unsigned.

`errors.UnrecognisedError`

python

UnrecognisedError(message: str, *, code: str, hint: str | None = None, status: int | None = None)

Bases: GuardianAgentError

An error with a code this SDK doesn’t know, from a newer proxy.

Its code, message and hint are the proxy’s own.

Parameters:

message (str) – The proxy’s message.
code (str) – The proxy’s code.
hint (str | None) – The proxy’s hint.
status (int | None) – The proxy’s HTTP status.