Skip to main content
The SDK raises typed exceptions for common integration failures and returns typed objects for sandbox, process, file, template, volume, desktop, SSH relay, and code interpreter data.

​
Exceptions

ExceptionUse
SandboxErrorBase SDK/runtime error.
AuthErrorMissing, invalid, or rejected API credentials.
NotFoundErrorSandbox, snapshot, volume, template, or file was not found.
TimeoutErrorOperation exceeded its configured timeout.
BuildErrorTemplate build failed.
FileUploadErrorUpload failed; may include an upload_id for resume.
GitErrorGit helper operation failed.
BatchWriteErrorMulti-file write partially failed.
from nullspace import AuthError, Sandbox, TimeoutError

try:
    sandbox = Sandbox.create(template="base", timeout=30)
except AuthError:
    print("check NULLSPACE_API_KEY")
except TimeoutError:
    print("sandbox did not become ready in time")

​
Typed Results

Common result objects include sandbox info, command result, process info, upload/download result, template build status, volume info, lifecycle events, desktop stream info, PTY result, PreviewUrl, PreviewGrantInfo, PreviewReadiness, PreviewProxyTarget, RevokePreviewGrantResponse, SshAccess certificate relay metadata, code execution, code contexts, code runs, and artifacts. Field names match the Python SDK types and the generated OpenAPI schemas where possible. PreviewGrantInfo includes safe grant inventory fields such as first/last use, HTTP request count, WebSocket connection count, byte counters, last error code/time, and disabled time. Use redact_preview_url(...) and redact_preview_token(...) before displaying preview bearer credentials in logs, terminals, or support artifacts.