Skip to main content
Agent Sandbox reports a failure in three ways: the SDK raises an exception or error class, the API returns a status that the SDK maps to one of those classes, and the CLI prints a message and sets an exit code. This page is the reference for all three.
Install the SDK, or the CLI for ppio commands, and set the PPIO_API_KEY and PPIO_DOMAIN environment variables before running these examples. See Quickstart and Install and authenticate.

SDK errors

The Python SDK raises these classes from ppio_sandbox.core.exceptions, plus CommandExitException from ppio_sandbox.core.sandbox.commands.command_handle. The Node.js SDK exports the matching classes from ppio-sandbox.
SandboxError
The base class for all sandbox errors. Typical cause: a sandbox failure that no other class covers, including an API status with a message body. Retry: not stated.
TimeoutError
A timeout occurred. The class covers a sandbox timeout (unavailable), a request timeout (canceled) and a deadline for a process or watch (deadline_exceeded). Typical cause: the sandbox reached its timeout, or a request or process exceeded its own. Retry: increase the timeout that expired. For a sandbox timeout, pass timeout / timeoutMs at creation or call set_timeout() / setTimeout(); for a request timeout, raise request_timeout / requestTimeoutMs. The error message names the option.
InvalidArgumentError
An invalid argument was provided. Typical cause: a value or option that the SDK rejects. Retry: not stated.
NotEnoughSpaceError
There is not enough disk space. Typical cause: the sandbox filesystem is full. Retry: not stated.
NotFoundError
A resource was not found. Kept for compatibility; use FileNotFoundException or SandboxNotFoundException. Typical cause: the resource is missing. Retry: not stated.
FileNotFoundError
A file or directory is not found inside a sandbox. Typical cause: a path that does not exist in the sandbox. Retry: not stated.
SandboxNotFoundError
A sandbox is not found. Typical cause: the sandbox does not exist or is no longer running. Resuming a paused sandbox that was killed or never existed raises it with the message Paused sandbox <sandbox-id> not found. Code that catches NotFoundException / NotFoundError also catches it. Retry: not stated.
AuthenticationError
Authentication failed. Typical cause: a missing or invalid API key; the SDK maps an HTTP 401 response to this class. Retry: not stated.
GitAuthError
Git authentication failed. Typical cause: invalid Git credentials for a clone or a push. Retry: not stated.
GitUpstreamError
Git upstream tracking is missing. Typical cause: a push from a branch without an upstream. Retry: not stated.
TemplateError
The template uses an envd version that is not compatible with the SDK. Typical cause: a template built with an older envd. Retry: not stated.
RateLimitError
retryable
The API rate limit is exceeded. Typical cause: too many requests in a short interval. Retry: the SDK message says to try again later.
BuildError
The template build failed. Typical cause: invalid credentials for a private registry; a package install that fails inside run_cmd() / runCmd(); a start command that exits unexpectedly; a ready command that never succeeds; CPU and memory settings that do not satisfy platform limits, including a request over the tier maximums. Retry: not stated.
FileUploadError
A file upload failed. Typical cause: an upload during a template build that did not complete. Retry: not stated.
ImageConfigError
The registry configuration of a base image cannot be read, and the build was told to stop on that failure (on_config_failure="raise"). Typical cause: a base image whose registry needs credentials or cannot be reached. Retry: not stated.
CommandExitError
A command exited with a non-zero exit code. It carries stdout, stderr, exit_code (exitCode in Node.js) and error, so the output can still be inspected after the failure. Typical cause: the command run in the sandbox returned a non-zero code. Retry: not stated.
In Python, AuthenticationException and BuildException inherit from Exception, not from SandboxException. In Node.js, AuthenticationError and BuildError inherit from Error. Catch them separately from the sandbox errors.

API responses

The SDK maps the status of a failed request to one of the classes above.
AuthenticationException · AuthenticationError
Unauthorized. The message reads 401: Unauthorized, please check your credentials. in Python and Unauthorized, please check your credentials. in Node.js.
SandboxException · SandboxError
The balance cannot cover a new sandbox. The message reads 402: insufficient balance. Do not retry; stop the batch and top up the balance.
RateLimitException · RateLimitError
retryable
Rate limit exceeded. The message says to try again later.
Any other error status raises the default class of the call, with the status and the message from the response: SandboxException / SandboxError for most calls, BuildException / BuildError for a template build request. For a 402 response, handle the error in code so a batch stops cleanly instead of retrying:

CLI messages and exit codes

On failure the CLI prints the message and exits with a non-zero code. Some commands report a specific exit code instead.
Last modified on November 19, 2026