Exceptions¶
Every error the SDK raises is a subclass of RunVaultError.
| Exception | Meaning |
|---|---|
RunVaultError |
Base class for every SDK exception. |
NoActiveRunError |
An LLM call fired outside with identity.run():. |
CrossIdentityError |
LLM bound to one identity invoked under another identity's run (hard mode). |
CrossIdentityWarning |
Same situation, soft mode — emitted as a warning, not raised. |
UntrustedHostError |
Attempted to attach signed credentials to a non-proxy URL. |
BudgetExceededError |
Agent has spent its budget cap. |
TokenExpiredError |
Proxy rejected the JWT (401, JWT_EXPIRED, …). |
ProxyError |
Proxy returned a structured error not mapped to a more specific type. |
LLMProviderError |
Upstream provider (OpenAI, Anthropic, …) returned an error. |
AuthenticationError |
Backend rejected the API key. |
AgentSuspendedError |
Administrator suspended the agent. SDK will not retry. |
RegistrationError |
Backend registration / refresh failed for another reason. |
ConfigurationError |
Misconfigured SDK or environment. |
ConnectionError |
Network failure talking to the backend. (Distinct from Python's built-in ConnectionError.) |
Every RunVaultError carries three optional attributes:
| Attribute | Meaning |
|---|---|
status_code |
Original HTTP status from the backend or proxy, if any. |
error_code |
Machine-readable error code (e.g. BUDGET_CAP_REACHED). |
user_string |
A short, UI-friendly message safe to display. |
Reference¶
runvault.exceptions.RunVaultError
¶
Bases: Exception
Base class for all RunVault SDK exceptions.
Attributes:
| Name | Type | Description |
|---|---|---|
status_code |
HTTP status code from the backend or proxy, if available. |
|
error_code |
Machine-readable code (e.g. |
|
user_string |
Human-readable message safe to display to end users. |
runvault.exceptions.NoActiveRunError
¶
Bases: RunVaultError
current_run() called outside a with identity.run(): block.
The SDK never falls back to a default run — a missing run is a
programming error, not a recoverable condition. Wrap the call in
with identity.run(): before invoking the LLM.
runvault.exceptions.CrossIdentityError
¶
Bases: RunVaultError
An LLM bound to one identity was invoked under another identity's run.
Raised by the transport when security_policy="hard" (the default).
Catches accidental cross-wiring between agents in multi-identity
codebases. With security_policy="soft", the SDK emits
:class:CrossIdentityWarning instead and lets the call proceed
using the bound identity's key.
runvault.exceptions.CrossIdentityWarning
¶
Bases: Warning
Emitted in security_policy="soft" mode when a bound LLM is
invoked under a different identity's active run.
The request proceeds using the bound identity's key (the transport cannot sign with keys it doesn't hold), so the bound identity is billed — not the run owner.
runvault.exceptions.UntrustedHostError
¶
Bases: RunVaultError
The transport refused to attach RunVault credentials to a non-proxy host.
The transport signs every outbound request with the agent's
private key. A user-held identity.http_client() aimed at any
other URL would otherwise exfiltrate a valid signed JWT. The host
allowlist closes this off — only the configured proxy host is
permitted.
runvault.exceptions.BudgetExceededError
¶
Bases: RunVaultError
Agent's spending budget is exhausted — the proxy denied the request.
Attributes:
| Name | Type | Description |
|---|---|---|
remaining_usd |
Balance remaining at time of denial (may be 0 or slightly negative due to estimation rounding). |
runvault.exceptions.TokenExpiredError
¶
Bases: RunVaultError
Proxy JWT has expired — call RunVault.init() again to get a new one.
runvault.exceptions.ProxyError
¶
Bases: RunVaultError
Generic proxy-level error (e.g. version mismatch, proxy misconfiguration).
runvault.exceptions.LLMProviderError
¶
Bases: RunVaultError
The upstream LLM provider returned an error response.
This wraps provider HTTP errors so agents can catch all LLM failures from a single exception type without importing provider-specific SDKs.
Attributes:
| Name | Type | Description |
|---|---|---|
provider |
Name of the provider (e.g. |
runvault.exceptions.AuthenticationError
¶
Bases: RunVaultError
API key is invalid, revoked, or has no linked LLM vault key.
runvault.exceptions.AgentSuspendedError
¶
Bases: RunVaultError
Agent has been administratively suspended.
Raised when the backend returns 403 AGENT_SUSPENDED from either init() or /credentials/refresh. The agent's status has been set to 'revoked' by an admin via the dashboard. The SDK CANNOT recover from this state on its own — an admin must click "Reactivate" in the dashboard, after which the agent's next call automatically obtains fresh credentials via /credentials/refresh.
Catching this exception should surface a permanent-failure message to operators (e.g. "Your administrator has suspended this agent. Contact them to reactivate it."). Do NOT auto-retry; do NOT fall back to other auth paths.
runvault.exceptions.RegistrationError
¶
Bases: RunVaultError
Agent registration with the RunVault backend failed.
runvault.exceptions.ConfigurationError
¶
Bases: RunVaultError
Required SDK configuration is missing or invalid (e.g. no proxy URL).
runvault.exceptions.ConnectionError
¶
Bases: RunVaultError
RunVault backend could not be reached (network error or timeout).