Errors
Stage-attributed error taxonomy for the code_interpreter SDLC.
A single, shared exception hierarchy for sandbox and template creation/execution
failures. Every error carries the failing stage (stamped at the raise site, not
an outer catch) and exposes transient — derived solely from #5418's
BaseSandbox._is_transient_create_error so retry logic and user-facing surfacing
never drift.
CodeInterpreterError(message, *, stage, classifier=None)
Bases: RuntimeError
Base class for every stage-attributed code_interpreter failure.
Subclasses RuntimeError deliberately: every failure this taxonomy replaces was raised
as a bare RuntimeError before, so existing except RuntimeError callers keep working
while new callers can except CodeInterpreterError and branch on stage / transient.
Attributes:
| Name | Type | Description |
|---|---|---|
stage |
Stage
|
The SDLC stage at which the failure occurred. |
Initialize the error with a stage and an optional transience classifier.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable, user-facing message. |
required |
stage
|
Stage
|
The stage at which the failure occurred. |
required |
classifier
|
TransientClassifier | None
|
A reference to the transient
predicate to apply across the |
None
|
transient
property
Whether this failure is transient and worth retrying.
Walks this error and its __cause__ chain, applying #5418's classifier.
No parallel classification and no stored flag — the verdict is derived on read.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if any exception in the chain is classified transient. |
SandboxExecutionError(message, *, stage, classifier=None)
SandboxNotInitializedError(message='Sandbox is not initialized', **kwargs)
Bases: CodeInterpreterError
An operation was attempted before the sandbox was initialized/started.
Initialize with the shared not-initialized message and NOT_INITIALIZED stage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
Human-readable message. Defaults to "Sandbox is not initialized". |
'Sandbox is not initialized'
|
**kwargs
|
Any
|
Forwarded to |
{}
|
SandboxStartError(message, *, stage, classifier=None)
SandboxTerminateError(message, *, stage, classifier=None)
Bases: CodeInterpreterError
Teardown failed after every retry (stage is TERMINATE).
Replaces the provider SDK's raw exception, which is preserved as __cause__. The sandbox
may still be alive on the server, so providers keep their handle for the caller to retry.
Stage
Bases: StrEnum
The stage of the code_interpreter SDLC at which a failure occurred.
The string value doubles as the error.code field in JSON logs (via
extra={"error_code": stage}), so keep the values stable and queryable.