jeevesagent.core.errors

Exception hierarchy.

All harness-raised exceptions inherit from JeevesAgentError so callers can catch the family without binding to specific subtypes.

Exceptions

AuthenticationError	Invalid, missing, or revoked API credentials.
BudgetExceeded	A run was halted because a budget limit was hit.
CancelledByUser	A user-driven interruption (signal, timeout) ended the run.
ConfigError	Invalid or unresolvable configuration passed to Agent.
ContentFilterError	The provider's safety system blocked the request or response.
FreshnessError	A certified value failed its freshness policy.
InvalidRequestError	The request was malformed or violated the provider's API
JeevesAgentError	Base class for all harness errors.
LineageError	A certified value failed its lineage policy.
MCPError	An MCP transport, handshake, or protocol error.
MemoryStoreError	The memory backend failed an operation.
ModelError	A call to the underlying model adapter failed.
OutputValidationError	The model's final answer did not validate against the supplied
PermanentModelError	A model call failed in a way that retrying will not fix.
PermissionDenied	A tool call was denied by the permission layer or a user hook.
RateLimitError	The provider returned a 429 / quota-exhausted response.
RuntimeJournalError	The durable runtime journal is unreadable or inconsistent.
SandboxError	The sandbox refused or failed to execute a tool.
ToolError	A tool invocation failed at the tool's own boundary.
TransientModelError	A model call failed in a way that may succeed on retry.

Module Contents

exception jeevesagent.core.errors.AuthenticationError(message: str, *, cause: BaseException | None = None)

Bases: PermanentModelError

Invalid, missing, or revoked API credentials.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.BudgetExceeded(reason: str)

Bases: JeevesAgentError

A run was halted because a budget limit was hit.

Initialize self. See help(type(self)) for accurate signature.

reason

exception jeevesagent.core.errors.CancelledByUser

Bases: JeevesAgentError

A user-driven interruption (signal, timeout) ended the run.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.ConfigError

Bases: JeevesAgentError

Invalid or unresolvable configuration passed to Agent.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.ContentFilterError(message: str, *, cause: BaseException | None = None)

Bases: PermanentModelError

The provider’s safety system blocked the request or response.

Typically a permanent failure for the same prompt; users may rephrase but the framework should not silently retry.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.FreshnessError

Bases: JeevesAgentError

A certified value failed its freshness policy.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.InvalidRequestError(message: str, *, cause: BaseException | None = None)

Bases: PermanentModelError

The request was malformed or violated the provider’s API contract — bad parameters, oversized prompt, unknown model name, etc. Fix the request, don’t retry.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.JeevesAgentError

Bases: Exception

Base class for all harness errors.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.LineageError

Bases: JeevesAgentError

A certified value failed its lineage policy.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.MCPError

Bases: JeevesAgentError

An MCP transport, handshake, or protocol error.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.MemoryStoreError

Bases: JeevesAgentError

The memory backend failed an operation.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.ModelError(message: str, *, cause: BaseException | None = None)

Bases: JeevesAgentError

A call to the underlying model adapter failed.

Base of the model-error taxonomy: catch this to handle every model failure regardless of whether it is transient or permanent. The SDK exception that triggered the classification is attached via __cause__ (and cause) so debug code can still inspect the raw error.

Initialize self. See help(type(self)) for accurate signature.

cause = None

exception jeevesagent.core.errors.OutputValidationError(message: str, *, raw: str, schema: type, cause: BaseException | None = None)

Bases: JeevesAgentError

The model’s final answer did not validate against the supplied output_schema.

Raised by Agent.run() when the caller passed output_schema= and the model’s final assistant text could not be parsed/validated as the requested Pydantic model — even after the optional one-shot “retry with the validation error” turn.

Carries the raw model output (raw), the underlying Pydantic pydantic.ValidationError (cause, also exposed via __cause__), and the schema that was being targeted (schema) so callers can build whatever recovery strategy they need (re-prompt with extra examples, fall back to free-text, etc.).

Initialize self. See help(type(self)) for accurate signature.

cause = None

raw

schema

exception jeevesagent.core.errors.PermanentModelError(message: str, *, cause: BaseException | None = None)

Bases: ModelError

A model call failed in a way that retrying will not fix.

Wrong API key, malformed request, content-filter rejection, deprecated model name, etc. The retry layer raises these immediately without backoff so callers can fail fast and surface the real problem.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.PermissionDenied(tool: str, reason: str)

Bases: JeevesAgentError

A tool call was denied by the permission layer or a user hook.

Initialize self. See help(type(self)) for accurate signature.

reason

tool

exception jeevesagent.core.errors.RateLimitError(message: str, *, retry_after: float | None = None, cause: BaseException | None = None)

Bases: TransientModelError

The provider returned a 429 / quota-exhausted response.

Carries retry_after when the provider supplied one. Subclass of TransientModelError so generic transient handlers cover it; catch RateLimitError specifically when you need to surface “slow down” to the caller (e.g. propagate a 429 to your own clients).

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.RuntimeJournalError

Bases: JeevesAgentError

The durable runtime journal is unreadable or inconsistent.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.SandboxError

Bases: JeevesAgentError

The sandbox refused or failed to execute a tool.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.ToolError

Bases: JeevesAgentError

A tool invocation failed at the tool’s own boundary.

Initialize self. See help(type(self)) for accurate signature.

exception jeevesagent.core.errors.TransientModelError(message: str, *, retry_after: float | None = None, cause: BaseException | None = None)

Bases: ModelError

A model call failed in a way that may succeed on retry.

Covers HTTP 5xx responses, network errors, timeouts, and provider-side rate limits. The retry layer treats this family as retryable and applies backoff.

retry_after (in seconds) carries a provider-supplied hint when one is available — e.g. an Retry-After HTTP header on a 429 response. The retry layer respects the larger of the policy’s computed backoff and retry_after so we never wait less than the provider asked for.

Initialize self. See help(type(self)) for accurate signature.

retry_after = None