---
title: "Errors"
description: "Every error the SDK raises, from guardian_agent.errors, and proxy_error, which recovers the SDK's error from a model client's."
source: "Guardian Agent SDK"
---
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

{/* generated api guardian_agent.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.

{/* end generated */}

## guardian_agent.errors

{/* generated api 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**](#errorsguardianagenterror) – The base of every error the SDK raises.
- [**ProxyError**](#errorsproxyerror) – The local Viper proxy can't be used: down, incompatible or refusing.
- [**ProxyUnreachable**](#errorsproxyunreachable) – Nothing answered at the proxy's address, or it didn't answer in time.
- [**ProxyIncompatible**](#errorsproxyincompatible) – The proxy lacks the agent API, definition schema or features this SDK uses.
- [**NotLocal**](#errorsnotlocal) – The proxy refused the call because it didn't come from this machine.
- [**NotFound**](#errorsnotfound) – The proxy has no such endpoint; usually a proxy older than the SDK.
- [**MethodNotAllowed**](#errorsmethodnotallowed) – The endpoint exists but not for that method; a version mismatch.
- [**ProxyInternalError**](#errorsproxyinternalerror) – The proxy failed in a way the caller can't fix; its log says why.
- [**UpstreamUnreachable**](#errorsupstreamunreachable) – The proxy couldn't reach the gateway, so nothing was sent.
- [**RequestUnreadable**](#errorsrequestunreadable) – The proxy couldn't take in the request's body.
- [**UpstreamResponseLost**](#errorsupstreamresponselost) – The request was sent, but no complete answer came back.
- [**UnexpectedResponse**](#errorsunexpectedresponse) – The proxy answered with something this SDK can't read.
- [**DefinitionError**](#errorsdefinitionerror) – The agent definition breaks a rule; nothing was registered.
- [**DefinitionInvalid**](#errorsdefinitioninvalid) – The definition breaks the schema or a validation rule.
- [**DefinitionTooLarge**](#errorsdefinitiontoolarge) – The definition, or part of it, is over one of the proxy's limits.
- [**DefinitionContainsSecret**](#errorsdefinitioncontainssecret) – The definition looks like it holds a credential, which is never recorded.
- [**SchemaVersionUnsupported**](#errorsschemaversionunsupported) – The proxy doesn't accept this definition schema version.
- [**CollectionInvalid**](#errorscollectioninvalid) – A skill's or memory source's files can't be stored as given; none were.
- [**CollectionTooLarge**](#errorscollectiontoolarge) – A skill's or memory source's files are over one of the proxy's limits.
- [**AgentError**](#errorsagenterror) – The proxy couldn't match a request to an enrolled agent and definition.
- [**AgentHeaderRequired**](#errorsagentheaderrequired) – The proxy only signs requests that name an agent, and this one didn't.
- [**AgentHeaderInvalid**](#errorsagentheaderinvalid) – An agent header was repeated, empty or not text.
- [**AgentNotEnrolled**](#errorsagentnotenrolled) – No agent of that name is enrolled on this proxy.
- [**DefinitionUnknown**](#errorsdefinitionunknown) – The definition isn't registered for this agent on the proxy.
- [**SubagentUnknown**](#errorssubagentunknown) – The definition has no sub-agent of that name.
- [**SigningFailed**](#errorssigningfailed) – The proxy couldn't sign the request, so it didn't forward it.
- [**ModelNotRoutedThroughProxy**](#errorsmodelnotroutedthroughproxy) – A model client points somewhere other than the proxy, so it would go unsigned.
- [**UnrecognisedError**](#errorsunrecognisederror) – 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**](#errorsguardianagenterrorcode) (`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.

{/* end generated */}