jaz.exceptions
New to JAZ? This is generated API reference. Start with the docs and the concepts overview.
Public API of the jaz.exceptions submodule (import from jaz.exceptions, e.g. from jaz.exceptions import ...).
Every error defined here derives from JazException, which derives from Exception, so
except JazException around jaz.invoke catches any of them. The module also publishes
one warning category, UnknownRequestParamWarning, which is a UserWarning rather than
an error.
Configuring JAZ is not agent execution and does not go through this taxonomy: calling a setup
function wrongly raises the builtin that fits (ValueError, TypeError), and a component
validating input with someone else’s library raises that library’s error — registering a template
loader surfaces jinja2.TemplateSyntaxError. Each such function documents what it raises.
JazException
Section titled “JazException”Bases: Exception
Base exception class for JAZ-related errors.
FatalError
Section titled “FatalError”Bases: JazException
Class of exceptions that cause invoke to error out instead of being shown to the
agent as recoverable feedback; exempt from being caught by agent-written except clauses.
An ordinary exception in REPL code is caught and shown to the agent as recoverable feedback
(a Continue) so it can retry. A FatalError instead ends the REPL session and
causes the invoke to error out with that error. If this
invoke is a subinvoke of a parent invoke and the FatalError occurs in the REPL of that
parent invoke, then that parent invoke also errors out. Thus, usually, the
entire invoke tree fails and the top-level invoke raises the
FatalError.
Raise FatalError when a fatal error occurs that the invoke tree cannot recover from. For
example, write raise FatalError() inside a tool definition in paths that should take
down the entire invoke tree. Errors from third-party libraries that you’d like to convert to
a fatal error should be caught and re-raised as FatalError. A hook that would like to
take down the entire invoke tree should emit an Abort(error=FatalError(...)) effect.
(Emitting Abort(error=exc) where exc is not a FatalError aborts the in-progress
invoke but does not propagate to the parent invoke.)
Who can decline a fatal error, since that is the whole point of the class:
| Agent REPL code | No — a FatalError is exempt from being caught by agent-written except and except* clauses. Two known exceptions, both under “Known limitations”. |
| User code | Yes, by catching it — a tool or the caller is host code, and one that catches its own fatal error has decided not to fail. |
| A hook | No — a fatal exception propagates during unwind, and no transform boundary fires on the unwind path, so there is no effect a hook could return to convert it back into normal control flow. |
The purpose of this class is routing, i.e. who the error is addressed to. An ordinary error is addressed to the agent; a fatal error is addressed to the caller: “this failure is not something the agent can fix by retrying.”
It is an Exception (through JazException), not a BaseException like
KeyboardInterrupt, because the caller is its audience: except Exception around
invoke catches it, as it catches every other error JAZ raises. The agent’s own
except Exception does not, as the table above says; that is the REPL’s doing, not the
base class’s.
Known limitations
Section titled “Known limitations”-
A suppressing context manager still swallows it, in the default configuration and with no imports:
class S:def __enter__(self): return selfdef __exit__(self, *a): return True # truthy -> suppresses anythingwith S():tool_that_raises_fatal() # fatal error swallowed; the run continuesA known limitation, not a boundary.
-
A group-wrapped fatal error is catchable. An
ExceptionGroupcontaining aFatalErroris really anExceptionGroup, so bothexcept Exceptionandexcept ExceptionGroupcatch it. Such a group is still exempt fromexcept*, which surfaces theFatalErrorleaf. A group that goes uncaught still takes down the invoke tree.
UnknownRequestParamWarning
Section titled “UnknownRequestParamWarning”Bases: UserWarning
Emitted when a backend construction kwarg looks like a misspelled request parameter.
A backend (e.g. jaz.llm.LiteLLM) forwards any keyword it does not name as a
per-request default onto the wire, so a typo like temperatrue=0.7 is otherwise sent
verbatim and silently ignored by the provider. When an unrecognized kwarg closely matches a
known request parameter, this warns with the suggested spelling — but the kwarg is still
forwarded, since arbitrary provider-specific extras are supported by design.
Filter it like any warning category:
import warnings, jazwarnings.simplefilter("ignore", jaz.exceptions.UnknownRequestParamWarning)warnings.simplefilter("error", jaz.exceptions.UnknownRequestParamWarning)ReturnTypeError
Section titled “ReturnTypeError”Bases: TypeError, JazException
Raised when the agent’s returned value doesn’t satisfy the declared return type.
Produced by jaz.hooks.ReturnType: a mismatched return is downgraded to a
Continue carrying this error, so the agent is told what it got wrong and can retry.
Past ReturnType’s max_failures it is raised out of the invoke instead, with the
offending value in the message. (jaz.hooks.ValidateReturn shows the agent its
validator’s own exception instead.)
FileAccessDeniedError
Section titled “FileAccessDeniedError”Bases: PermissionError, JazException
Raised when the REPL refuses a file operation its policy does not allow.
A PermissionError, so agent code handling a denied open the usual way
(except PermissionError or except OSError) handles this one too, as it would outside
the sandbox. What refuses it is the REPL’s own policy, not the operating system — usually
allowed_read_paths / allowed_write_paths, and the message then names the offending
path and the allowed patterns; errno is None. Opening a raw file descriptor is
refused outright instead, with no path to report, since there is nothing to check an
allow-list against.
BudgetExhaustedError
Section titled “BudgetExhaustedError”Bases: JazException
Raised when a budget-enforcing hook stops the run because its budget is spent.
The base of two distinct causes — catch this to handle either, or the subclass to tell
them apart: IterationLimitExhaustedError (the turn cap) and
BudgetPoolExhaustedError (a cost/calls pool). The distinction matters to a caller
that can do something different about each — e.g. offer more turns for the former but not
the latter, which more turns cannot refill.
IterationLimitExhaustedError
Section titled “IterationLimitExhaustedError”Bases: BudgetExhaustedError
Raised by jaz.hooks.IterationLimit when the per-invoke turn cap is reached.
A subclass of BudgetExhaustedError, so except BudgetExhaustedError still
matches; catch this specifically to react to the turn cap alone (granting more turns can
let the run finish, unlike a spent cost/calls pool).
BudgetPoolExhaustedError
Section titled “BudgetPoolExhaustedError”Bases: BudgetExhaustedError
Raised by jaz.hooks.BudgetPool when its pooled cost or calls ceiling is reached.
A subclass of BudgetExhaustedError, so except BudgetExhaustedError still
matches; catch this specifically to distinguish a spent cost/calls pool from the turn cap
(IterationLimitExhaustedError) — more turns cannot refill a pool.
RecursionLimitError
Section titled “RecursionLimitError”Bases: JazException
Raised when a jaz.invoke exceeds an invoke recursion limit set by
jaz.hooks.RecursionLimit.
InputRenderError
Section titled “InputRenderError”Bases: JazException
Raised when an invoke input cannot be rendered into the agent’s prompt.
Wraps whatever rendering the value raised – its own __str__/__repr__ failing, or
anything else – and names the input; the original is chained as __cause__. Rendering
happens before the invoke makes a single LLM call, so nothing has been spent.
It is never fatal: in a sub-invoke it reaches the parent agent as recoverable feedback,
so the parent can call again without the input. One case it cannot recover from on its
own: a value inherited from an enclosing jaz.scope is not the parent’s to remove,
so every sub-invoke under that scope fails the same way until the scope changes.
KeyboardInterrupt and other non-Exception signals are not wrapped and still end
the run.
BudgetForcingError
Section titled “BudgetForcingError”Bases: JazException
Raised when the jaz.hooks.BudgetForcing hook blocks an early
return/raise finish.
REPLInputConflictError
Section titled “REPLInputConflictError”Bases: JazException
Raised when an added name conflicts with a binding that already exists.
Two effects adding the same name with different values, an AddInputs key that
collides with a caller’s own input or scope entry, or an AddToNamespace name already
bound in the REPL namespace. Identical values coalesce instead of raising.
REPLTimeoutPragmaError
Section titled “REPLTimeoutPragmaError”Bases: ValueError, JazException
Raised when the code’s leading # timeout: comment names no positive number of seconds.
An agent sets a per-execution wall-clock bound with a # timeout: <seconds> comment among
the lines opening its REPL code. The value must parse as a positive, finite number, so
# timeout: 120s and # timeout: 0 are rejected; a trailing # comment after the
number is allowed. The offending code is not executed — the agent sees the error as ordinary
REPL feedback and can correct it on the next iteration.
KeyEditDeniedError
Section titled “KeyEditDeniedError”Bases: ValueError, JazException
Raised when an invoke input, or a namespace or input edit, names a key the REPL refuses to let it bind or drop.
Today that is __builtins__, which holds the REPL compiler’s allow-lists (which builtins,
imports and attributes the agent’s code may reach), so binding or dropping it would reopen
them. The framework refuses it, rather than skipping it, wherever it binds or drops a name
for a caller or a hook: an input passed to invoke or scope, or an
Add/Drop effect, for example. The REPL also raises it at the end of an exec whose code
replaced __builtins__ (through globals(), which the compiler cannot refuse), and on
every later read of the sandbox; that invoke then fails with it, and a parent invoke sees the
failure as ordinary feedback. The message names the key.
InvalidEffectError
Section titled “InvalidEffectError”Bases: JazException
Raised when a hook returns an effect at an event that does not accept it.
Every event documents the effects valid at its stage (supplies at *Send, transforms
at *Complete, Abort at every control event, the *Exit events accept
none). An out-of-stage effect is a hook bug — emitting it can only mean the hook expects
an influence the stage cannot deliver — so composition rejects it loudly rather than
ignoring it. The message names the offending effect kind and the event.
LLMResponseConflictError
Section titled “LLMResponseConflictError”Bases: JazException
Raised when hooks compose conflicting LLM-response values for the same query.
Two cases, both order-independence violations: two distinct SupplyLLMResponse effects
supplying a response at LLMQuerySend, or two ModifyLLMResponse effects setting
the same field to different values at LLMQueryComplete. Identical values coalesce;
distinct ones raise, because resolving by arrival order would make composition depend on hook
registration or with-nesting order.
ReturnValueConflictError
Section titled “ReturnValueConflictError”Bases: JazException
Raised when effects carrying distinct Return values fold at one boundary.
Applies wherever results fold — SupplyExecResult at REPLExecSend,
ModifyExecResult at REPLExecComplete, and ModifyInvokeResult at
InvokeComplete. Carried
Continue results merge (outputs concatenate, exceptions group) and identical return
values coalesce, but two different return values cannot be combined without picking a
winner by hook order.
BlackboardSeedConflictError
Section titled “BlackboardSeedConflictError”Bases: JazException
Raised while assembling a per-invoke blackboard’s generation 0.
Two hooks seeding the same key with different values: the board cannot pick one without
depending on hook order. Surfaces before InvokeEnter is dispatched.
BlackboardWriteConflictError
Section titled “BlackboardWriteConflictError”Bases: JazException
Raised when two BlackboardWrite effects in one event write the same key
with different values.
Identical writes coalesce; distinct ones raise, since within an event the write order across hooks is irrelevant by design and has no order-independent resolution. Writes in different events are fine — the later generation overwrites.
HookActivationError
Section titled “HookActivationError”Bases: JazException
Raised when one Hook instance is activated by more than one path at a time.
A hook instance is active via exactly one path: the propagating with MyHook():, or a
single positional argument to one invoke. Overlapping them (with h: jaz.invoke(h, ...)),
listing it twice (jaz.invoke(h, h, ...)), or re-entering it while active would run its
setup()/teardown() more than once and clobber whatever it acquired.
ModelPricingUnavailableError
Section titled “ModelPricingUnavailableError”Bases: JazException
Raised when a cost_budget is set but no per-call cost is available to enforce it.
The usual cause is a model the backend cannot price — LiteLLM has no entry for it, or the
backend does not set LLMResponse.cost_usd at all. Use calls_budget, which counts LLM
calls and needs no rates. Custom or self-hosted models reached through a base_url are
rarely priced, so calls_budget is the way to cap them. Nothing is spent before this is
raised, unless the backend’s model_info.can_report_cost (see jaz.llm.ModelInfo)
promised a cost that a call then came back without: jaz.llm.GitHubCopilotLLM does
when GitHub leaves a call’s credit figure out, and a custom backend can.
ConfigOverrideActivationError
Section titled “ConfigOverrideActivationError”Bases: JazException
Raised when one ConfigOverride instance is entered while already active.
An instance is active within exactly one live scope at a time. Re-entering the same one —
nested on a thread or concurrently from another — is forbidden, mirroring
HookActivationError. Distinct instances nest freely and sequential reuse is fine;
only overlapping reuse of one instance trips the guard.
CodeEditOffsetError
Section titled “CodeEditOffsetError”Bases: IndexError, JazException
Raised when an InsertCode / DeleteCode character offset is out of range.
The character-offset twin of MessageEditIndexError: offsets follow list semantics
against the code the hook saw on REPLExecEnter (a negative offset counts from the
end; end-of-string is offset == len). Anything outside [-len, len] — or a
DeleteCode whose resolved start exceeds its end — raises rather than being
ignored or clamped, since every offset is computed against that exact snapshot and so an
out-of-range one is a hook bug.
Both an IndexError and a JazException, mirroring MessageEditIndexError.
MessageEditIndexError
Section titled “MessageEditIndexError”Bases: IndexError, JazException
Raised when a DropMessages / AddMessages index is out of range.
Indices follow list semantics against the snapshot the hook saw on LLMQueryEnter: a
negative index counts from the end, and append is index == len. Anything outside
[-len, len] for an add or [-len, len-1] for a drop raises rather than being ignored
or clamped.
Both an IndexError and a JazException, so except IndexError catches it as the
out-of-range failure it is, while except JazException still catches everything JAZ raises.
MissingDropTargetError
Section titled “MissingDropTargetError”Bases: KeyError, JazException
Raised when a DropFromNamespace / DropInputs names a target that isn’t present.
As with Python’s del, a builtin the sandbox allows (len) that no variable shadows is
not present: it is the sandbox’s policy, not a variable. Dropping a name that isn’t there is
a hook bug — a typo, or a re-drop-every-turn pattern that should be first-turn-only — so it
fails loud instead of no-op’ing. Set allow_missing=True for a deliberately defensive
drop.
LLMError
Section titled “LLMError”Bases: JazException
Base class for the provider/transport errors raised around an LLM call.
Catch it to handle any provider failure without naming each subclass. Each subclass documents whether it is retryable.
The names follow the openai and anthropic SDKs where they define the error
(BadRequestError, APITimeoutError, APIConnectionError, …),
LiteLLM’s where only LiteLLM does (ContextWindowExceededError, …), and otherwise
another framework’s (ServerError, google-genai’s) or JAZ’s own
(QuotaExceededError). Unlike those SDKs’ APIError, which every API error
subclasses, the root here is LLMError.
Every attribute but message is None when the backend did not see it: no response
came back (a timeout, a refused connection), or the backend does not expose it.
Attributes
message— The error message, the provider’s where it gave one.status_code— The HTTP status the provider answered with.body— The provider’s response body, decoded from JSON where it is JSON, else its text: its error body, or onjaz.llm.SGLangLLMa 200 it could not use or whose request was aborted.headers— The provider’s response headers, with lowercase names.code— The provider’s machine-readable error code, such as"credit_balance_exhausted"or"rate_limit_error": the first string among the error object’scode,typeandstatusfields (OpenRouter’smetadata.error_typeafter them), else Bedrock’sx-amzn-ErrorTypeheader; onjaz.llm.GitHubCopilotLLM, the Copilot runtime’s error code.request_id— The provider’s request id (thex-request-id,request-idorx-amzn-RequestIdheader; onjaz.llm.GitHubCopilotLLM, GitHub’sx-github-request-id, else the Copilot service’s), to quote when reporting a problem to the provider.retry_after— How long the provider asked the caller to wait before retrying, in seconds, from itsretry-after-msorretry-afterheader, else theretryDelayGemini and Vertex put in the body. A value that is not a finite, non-negative number is stored asNone. A backend’s retry waits this long plus jitter; a zero waits the usual backoff, and one longer thanRetryPolicy.retry_after_maxstops the retries.is_retryable— Whether to retry it whatever its class, as the provider said in anx-should-retryheader (read byjaz.llm.LiteLLMandjaz.llm.SGLangLLM;jaz.llm.GitHubCopilotLLM’s runtime passes no response headers);Noneleaves it to the class, and onlyTrueorFalseis stored. Retry caps still apply, aretry_afterlonger thanRetryPolicy.retry_after_maxstops the retries even when it isTrue.
LLMError.__init__
Section titled “LLMError.__init__”__init__(message: str, status_code: int | None = None, *, body: Any = None, headers: Mapping[str, str] | None = None, code: str | None = None, request_id: str | None = None, retry_after: float | None = None, is_retryable: bool | None = None) -> NoneRateLimitError
Section titled “RateLimitError”Bases: LLMError
Raised when the provider refuses the call for now, in a way that clears by retrying without
anyone acting: a per-minute or other rolling-window limit, a 429, a 402 that says how long to
wait and names no quota, or on jaz.llm.GitHubCopilotLLM a per-session spending cap that
a new session resets. A limit that needs someone to act, or lasts until a calendar reset, is a
QuotaExceededError instead, and the provider’s quota code says so at a 429 too.
Retried by default, after the wait the provider asks for (retry_after); a wait longer
than RetryPolicy.retry_after_max is not retried, and retry_after says when to try
again.
QuotaExceededError
Section titled “QuotaExceededError”Bases: LLMError
Raised when the account’s or project’s quota, credit or spend limit is used up, so the
call cannot succeed until someone acts (adds credit, raises a budget, enables billing) or
the quota resets on the calendar (a daily quota, a monthly allowance or spend cap). A limit
that clears by retrying without anyone acting (a rolling window, a stated wait, a new
session) is a RateLimitError instead.
Not retried by default, since resending cannot fix it, unless the provider’s
x-should-retry header says to. To keep retrying while someone tops up the account, opt
in: RetryPolicy(extra_retryable_exceptions=[QuotaExceededError]).
Every backend raises it for a 402 status unless the 402 says how long to wait and names no
quota, or, on jaz.llm.GitHubCopilotLLM, is the per-session spending cap on a reused
session that spent on earlier turns; and for the provider’s own quota codes at any other status.
jaz.llm.LiteLLM also recognizes a provider’s documented quota message, and raises it
when litellm.max_budget is spent. An error a backend does not recognize as a quota surfaces
as whatever class its status maps to, typically RateLimitError or
BadRequestError.
AuthenticationError
Section titled “AuthenticationError”Bases: LLMError
Raised when API authentication fails (invalid API key, etc.).
Not retried by default - the API key or credentials need to be fixed.
NotFoundError
Section titled “NotFoundError”Bases: LLMError
Raised when the request went to the wrong place, so the model name or the base URL has to change.
Usually a 404, with two realistic causes:
- the model name does not exist, or names a model the account is not entitled to — by
far the common case, and the first thing to check. Most providers answer both with a 404
(OpenAI’s
model_not_foundreads “does not exist or you do not have access to it”); some send a 403 for the entitlement (PermissionDeniedError), Anthropic and Bedrock among them; - the base URL is wrong, so the route itself is missing: anyone pointed at vLLM, a LiteLLM proxy, Ollama, or Azure can 404 on the path rather than the model.
On Azure the model name is the deployment name, and a wrong one is a 404 too.
Also raised for a redirect (a 3xx) the backend does not follow, and for redirects that never
end, and for OpenAI’s model_not_found code whatever the status. A provider that answers
an unknown model with a plain 400 raises BadRequestError instead. On LiteLLM, a
301, 302 or 303 is followed as a GET, as browsers and httpx do, so it surfaces as whatever
the new address answers.
Not retried by default — the model name or base URL has to be corrected.
PermissionDeniedError
Section titled “PermissionDeniedError”Bases: LLMError
Raised when the provider answers 403 and nothing in its response says otherwise: the key
is valid — an invalid one is 401, AuthenticationError — but is not permitted the
request.
What a 403 covers differs by provider (a key outside the project’s scope, Bedrock’s model
access not enabled, OpenAI’s unsupported region), so the class is the status’s verdict
rather than one fix. A 403 whose body the backend recognizes as a content block, a quota or
a bad credential raises ContentPolicyViolationError, QuotaExceededError or
AuthenticationError instead; OpenRouter’s permission_denied covers a key’s
missing permission and a guardrail block alike, and arrives as this. A model the account is
not entitled to is a 404 (NotFoundError) or a 400 on most providers, not a 403.
Also raised where the provider says the account’s standing is the problem whatever the
status, such as a Gemini response stopped with PUP_LIMITED_DISABLED or Bedrock’s 404 for
an account that has not submitted Anthropic’s use-case form.
Not retried by default — a permission has to be granted, or the account’s standing restored.
BadRequestError
Section titled “BadRequestError”Bases: LLMError
Raised when what was asked has to change, so resending it unchanged usually fails the
same way: the provider rejects the request, the backend refuses to send it, or (as
ContentPolicyViolationError) the provider blocks the prompt or the response. Its
subclasses name a cause, such as ContextWindowExceededError for an input too long
for the model. Where nothing more is known the status decides: any 4xx with no class of its
own raises it, registered in HTTP or not (an invalid parameter, a request too large, Groq’s
498), except 408, 409 and 499, which are retried as ServerError (on
jaz.llm.SGLangLLM a 499 is RequestAbortedError). Where the backend
recognizes them, an account out of credit raises QuotaExceededError instead, and a
wrong model name or address NotFoundError.
Not retried by default. The message carries the reason, the provider’s where it sent one.
UnsupportedParamsError
Section titled “UnsupportedParamsError”Bases: BadRequestError
Raised when a request parameter or backend setting is not supported, before anything is
sent: jaz.llm.LiteLLM raises it for a parameter LiteLLM cannot translate for the
provider (set drop_params=True to drop such parameters instead), and for a LiteLLM
global the backend refuses, such as litellm.num_retries.
A BadRequestError, so except BadRequestError catches it. Not retried by
default.
ContextWindowExceededError
Section titled “ContextWindowExceededError”Bases: BadRequestError
Raised when the LLM input exceeds the model’s context window.
A BadRequestError, so except BadRequestError catches it. Not retried by
default, since the same input will not fit.
ContentPolicyViolationError
Section titled “ContentPolicyViolationError”Bases: BadRequestError
Raised when the provider blocks a prompt or response under its content or usage policy,
or the model refuses it: as an error status, or, on jaz.llm.LiteLLM and
jaz.llm.GitHubCopilotLLM, as a refusal or content filter signaled on a successful
response, where status_code is None since no error status came back. Models LiteLLM
routes through its Responses API bridge (such as gpt-5-pro and the -codex models)
lose a refusal, which arrives as an ordinary response; their content filter does raise. On
jaz.llm.LiteLLM it is also raised, with status_code None, when a guardrail
LiteLLM runs blocks the call. LiteLLM runs guardrails on async calls (jaz.ainvoke), and on
sync calls only for the models on that Responses API bridge.
A BadRequestError, so except BadRequestError catches it. Not retried by
default. The same input can pass when resent, so to retry it add it to
RetryPolicy.extra_retryable_exceptions.
ServerError
Section titled “ServerError”Bases: LLMError
Raised when the provider fails to answer the request properly: a server error (5xx), a
408 (Request Timeout) or 409 (Conflict), which the openai and anthropic SDKs also retry,
a 499 outside jaz.llm.SGLangLLM, a response that is not a valid completion, or a
failure no more specific class describes (such as a status outside 4xx and 5xx). A failed
transport, a timeout included, raises APIConnectionError instead.
A 5xx raises the subclass InternalServerError; on jaz.llm.SGLangLLM, a
success status whose response is not a valid completion raises
APIResponseValidationError.
Retried by default, with its subclasses (it is in BaseLLM.retryable_exceptions). On
jaz.llm.LiteLLM the original LiteLLM exception is chained as __cause__.
InternalServerError
Section titled “InternalServerError”Bases: ServerError
Raised when the provider answers with a server error status (5xx). A 529, Anthropic’s
“overloaded”, raises the subclass OverloadedError.
Retryable, as a ServerError; key RetryPolicy.limits on it to cap 5xx answers
apart from invalid responses.
OverloadedError
Section titled “OverloadedError”Bases: InternalServerError
Raised when the provider answers that it is overloaded (HTTP 529, as Anthropic sends).
Retryable, as an InternalServerError.
APIResponseValidationError
Section titled “APIResponseValidationError”Bases: ServerError
Raised when the provider answers with a success status but the response is not a valid
completion, such as a body that is not JSON, one missing a field the backend needs, an error
object in place of a completion, a tool call when no tools were offered, or a response that
fails a JSON schema the caller asked the backend to enforce
(litellm.enable_json_schema_validation on jaz.llm.LiteLLM). status_code is
the success status where the backend saw it, else None. jaz.llm.LiteLLM
detects only a body that is not JSON; JSON of the wrong shape surfaces as whatever class
LiteLLM’s own error maps to, which on some providers is not retried.
Retryable, as a ServerError: a garbled response is usually transient, and another
sample may pass the schema.
APIConnectionError
Section titled “APIConnectionError”Bases: LLMError, ConnectionError
Raised when the transport fails, rather than the server answering with an error: the
endpoint cannot be reached, the request cannot be sent, or no usable response comes back
(the connection drops, what arrives cannot be parsed or decoded, such as a body whose
compression is broken), or the call times out (the subclass APITimeoutError).
Retried by default; key RetryPolicy.limits on APIConnectionError to cap it, timeouts
included. If it persists, check the network and the endpoint the backend talks to (its base
URL, or for a CLI-backed backend, the CLI). It is also a builtin ConnectionError, so
except ConnectionError (and except OSError) catches it.
APITimeoutError
Section titled “APITimeoutError”Bases: APIConnectionError, TimeoutError
Raised when an LLM call times out before the provider answers.
An APIConnectionError, so except APIConnectionError and
limits={APIConnectionError: n} cover it too; key RetryPolicy.limits on
APITimeoutError to cap timeouts on their own, or raise the backend’s timeout. Retried by
default. It is also a builtin TimeoutError (and so an OSError), so
except TimeoutError catches it.
RequestAbortedError
Section titled “RequestAbortedError”Bases: LLMError
Raised when the server reports the request as aborted: on jaz.llm.SGLangLLM,
SGLang 0.5.17’s 499 for a request aborted before it was scheduled, or a request SGLang
aborted (a pause with mode="abort", a weight update, /abort_request) and answered
with a 200 carrying the partial generation, which is then in body. SGLang answers a
grammar failure the same way, so that raises it too, though nobody cancelled it.
Not retried by default, since an abort is normally meant to stop the request. To retry it,
add it to RetryPolicy.extra_retryable_exceptions; the retry re-sends the original prompt
from scratch and does not continue from the partial generation. A server’s
x-should-retry header still decides where it sends one. Raised in a sub-invoke, it
reaches the parent’s code as an ordinary exception, which can catch it and go on querying.
is_fatal
Section titled “is_fatal”is_fatal(e: BaseException) -> boolWhether e should end the whole agent run instead of becoming feedback.
Consulted at every REPL exec boundary: a caught exception either re-raises out of exec
and propagates out of the invoke (fatal) or is rendered as a recoverable Continue.
Two rules, in this order:
- Anything rooted outside
Exceptionis fatal —KeyboardInterrupt,SystemExit,GeneratorExit,asyncio.CancelledError. This is the recoverable-vs-fatal split the language already encodes, not a hand-maintained list. FatalErroris fatal, explicitly — including when it is nested anywhere inside a(Base)ExceptionGroup, at any depth. Containment, not majority: a fatal error bundled with ordinary ones stays fatal.
That is the only carve-out. MemoryError is not special-cased (CPython roots it under
Exception because OOM can be recoverable — the iteration and budget caps backstop a
retry loop), and neither is AssertionError — an agent’s own assert stays
recoverable. To make a third-party error fatal, rewrap it as a FatalError at the
raise site rather than extending this function.