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 fromppio_sandbox.core.exceptions, plus CommandExitException from ppio_sandbox.core.sandbox.commands.command_handle. The Node.js SDK exports the matching classes from ppio-sandbox.
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.
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.An invalid argument was provided. Typical cause: a value or option that the SDK rejects. Retry: not stated.
There is not enough disk space. Typical cause: the sandbox filesystem is full. Retry: not stated.
A resource was not found. Kept for compatibility; use
FileNotFoundException or SandboxNotFoundException. Typical cause: the resource is missing. Retry: not stated.A file or directory is not found inside a sandbox. Typical cause: a path that does not exist in the sandbox. Retry: not stated.
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.Authentication failed. Typical cause: a missing or invalid API key; the SDK maps an HTTP 401 response to this class. Retry: not stated.
Git authentication failed. Typical cause: invalid Git credentials for a clone or a push. Retry: not stated.
Git upstream tracking is missing. Typical cause: a push from a branch without an upstream. Retry: not stated.
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.
The API rate limit is exceeded. Typical cause: too many requests in a short interval. Retry: the SDK message says to try again later.
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.A file upload failed. Typical cause: an upload during a template build that did not complete. Retry: not stated.
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.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.API responses
The SDK maps the status of a failed request to one of the classes above.Unauthorized. The message reads
401: Unauthorized, please check your credentials. in Python and Unauthorized, please check your credentials. in Node.js.The balance cannot cover a new sandbox. The message reads
402: insufficient balance. Do not retry; stop the batch and top up the balance.Rate limit exceeded. The message says to try again later.
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: