SOURCE_API

SOURCE_API = "DAYTONA_API"

Wire-format source identifier for errors originating from the Daytona API. source = None means the response did not carry a structured envelope (treat as opaque).

SOURCE_DAEMON

SOURCE_DAEMON = "DAYTONA_DAEMON"

Wire-format source identifier for errors originating from the sandbox daemon (toolbox).

SOURCE_PROXY

SOURCE_PROXY = "DAYTONA_PROXY"

Wire-format source identifier for errors originating from the Daytona proxy.

DaytonaError

class DaytonaError(Exception)

Base error for Daytona SDK.

Example:

try:
    sandbox = daytona.get("missing-sandbox")
except DaytonaError as exc:
    print(exc.status_code)
    print(exc.code)
    print(exc.message)

Attributes:

• message str - Error message
• status_code int | None - HTTP status code (set only for errors translated from an HTTP response; None for client-side errors).
• code str | None - Machine-readable error code from the server envelope (None for client-side errors).
• source str | None - Originating service. None when the response did not carry a structured envelope. Otherwise one of :data:SOURCE_API, :data:SOURCE_DAEMON, :data:SOURCE_PROXY.
• headers dict[str, Any] - Response headers (empty for client-side errors).

DaytonaError.__init__

def __init__(message: str,
             status_code: int | None = None,
             headers: Mapping[str, Any] | None = None,
             code: str | None = None,
             source: str | None = None)

Initialize Daytona error.

Arguments:

• message str - Error message
• status_code int | None - HTTP status code if the error came from a Daytona service response.
• headers Mapping[str, Any] | None - Response headers if available
• code str | None - Machine-readable error code from the wire envelope
• source str | None - Originating service from the wire envelope. Left as None for SDK-side errors and for responses from services that don’t emit the envelope.

DaytonaError.error_code

@property
def error_code() -> str | None

Deprecated alias of :attr:code, kept for backward compatibility.

DaytonaNotFoundError

class DaytonaNotFoundError(DaytonaError)

Error for when a resource is not found (HTTP 404).

Example:

try:
    sandbox.fs.download_file("/workspace/missing.txt")
except DaytonaNotFoundError as exc:
    print(exc.status_code)

DaytonaAuthenticationError

class DaytonaAuthenticationError(DaytonaError)

Error for when authentication fails (HTTP 401).

Example:

try:
    for sandbox in daytona.list():
        print(sandbox.id)
except DaytonaAuthenticationError as exc:
    print(exc.status_code)

DaytonaForbiddenError

class DaytonaForbiddenError(DaytonaError)

Error for when the request is forbidden (HTTP 403).

Example:

try:
    daytona.get("sandbox-without-access")
except DaytonaForbiddenError as exc:
    print(exc.message)

DaytonaRateLimitError

class DaytonaRateLimitError(DaytonaError)

Error for when rate limit is exceeded (HTTP 429).

Example:

try:
    for sandbox in daytona.list():
        print(sandbox.id)
except DaytonaRateLimitError as exc:
    print(exc.code)

DaytonaConflictError

class DaytonaConflictError(DaytonaError)

Error for when a resource conflict occurs (HTTP 409).

Example:

try:
    params = CreateSandboxFromSnapshotParams(name="existing-sandbox")
    daytona.create(params)
except DaytonaConflictError as exc:
    print(exc.code)

DaytonaBadRequestError

class DaytonaBadRequestError(DaytonaError)

Error for malformed requests (HTTP 400).

The deprecated DaytonaValidationError alias remains for older callers that historically grouped both HTTP 400 and HTTP 422 validation failures under one name. New code should catch DaytonaBadRequestError and DaytonaUnprocessableEntityError explicitly.

Example:

try:
    Image.debian_slim("3.8")
except DaytonaBadRequestError as exc:
    print(exc.message)

DaytonaTimeoutError

class DaytonaTimeoutError(DaytonaError)

Error for when a timeout occurs.

Example:

try:
    sandbox.wait_for_sandbox_start(timeout=1)
except DaytonaTimeoutError as exc:
    print(exc.message)

DaytonaConnectionError

class DaytonaConnectionError(DaytonaError)

Error for when a network connection fails (can’t connect or mid-request drop).

DaytonaConnectionTimeoutError

class DaytonaConnectionTimeoutError(DaytonaConnectionError,
                                    DaytonaTimeoutError)

Error for when the transport layer times out connecting or reading from a Daytona service.

DaytonaGoneError

class DaytonaGoneError(DaytonaError)

Error for HTTP 410 — the target resource is permanently gone.

DaytonaUnprocessableEntityError

class DaytonaUnprocessableEntityError(DaytonaError)

Error for HTTP 422 — request is well-formed but semantically invalid.

DaytonaInternalServerError

class DaytonaInternalServerError(DaytonaError)

Error for HTTP 500 — server-side bug or unhandled condition.

DaytonaBadGatewayError

class DaytonaBadGatewayError(DaytonaError)

Error for HTTP 502 — an upstream dependency rejected or dropped the request.

DaytonaServiceUnavailableError

class DaytonaServiceUnavailableError(DaytonaError)

Error for HTTP 503 — the service is temporarily refusing traffic.

DaytonaGitAuthFailedError

class DaytonaGitAuthFailedError(DaytonaAuthenticationError)

Git auth credentials were rejected by the remote.

DaytonaGitRepoNotFoundError

class DaytonaGitRepoNotFoundError(DaytonaNotFoundError)

The requested git repository does not exist.

DaytonaGitBranchNotFoundError

class DaytonaGitBranchNotFoundError(DaytonaNotFoundError)

The requested git branch does not exist.

DaytonaGitBranchExistsError

class DaytonaGitBranchExistsError(DaytonaConflictError)

A git branch with this name already exists.

DaytonaGitPushRejectedError

class DaytonaGitPushRejectedError(DaytonaConflictError)

Git push was rejected (non-fast-forward / stale ref).

DaytonaGitDirtyWorktreeError

class DaytonaGitDirtyWorktreeError(DaytonaConflictError)

Worktree has uncommitted changes.

DaytonaGitMergeConflictError

class DaytonaGitMergeConflictError(DaytonaConflictError)

Git merge has conflicts that need manual resolution.

DaytonaGitTransportFailedError

class DaytonaGitTransportFailedError(DaytonaBadGatewayError)

The git remote was unreachable (DNS, TLS, connection or timeout failure).

DaytonaGitRemoteRejectedError

class DaytonaGitRemoteRejectedError(DaytonaUnprocessableEntityError)

The git remote rejected the operation (hooks, branch protection or quota).

DaytonaFileNotFoundError

class DaytonaFileNotFoundError(DaytonaNotFoundError)

Filesystem entry was not found.

DaytonaFileAccessDeniedError

class DaytonaFileAccessDeniedError(DaytonaForbiddenError)

Insufficient permissions for the filesystem operation.

DaytonaInvalidFilePathError

class DaytonaInvalidFilePathError(DaytonaBadRequestError)

The daemon rejected the supplied file path (code INVALID_FILE_PATH).

DaytonaFileReadFailedError

class DaytonaFileReadFailedError(DaytonaInternalServerError)

The daemon could not read the sandbox file (code FILE_READ_FAILED).

DaytonaLspServerNotInitializedError

class DaytonaLspServerNotInitializedError(DaytonaBadRequestError)

LSP server must be started via /lsp/start first.

DaytonaProcessExecutionTimeoutError

class DaytonaProcessExecutionTimeoutError(DaytonaTimeoutError)

A process exceeded its configured execution timeout.

DaytonaProcessNotFoundError

class DaytonaProcessNotFoundError(DaytonaNotFoundError)

The requested process is not running.

DaytonaSessionEndedError

class DaytonaSessionEndedError(DaytonaGoneError)

The shell session has ended.

DaytonaCommandAlreadyCompletedError

class DaytonaCommandAlreadyCompletedError(DaytonaGoneError)

The shell command already finished.

DaytonaA11yUnavailableError

class DaytonaA11yUnavailableError(DaytonaServiceUnavailableError)

The accessibility (AT-SPI) bus is not reachable.

DaytonaRecordingStillActiveError

class DaytonaRecordingStillActiveError(DaytonaConflictError)

The recording is still running; stop it first.

DaytonaRecordingFfmpegNotFoundError

class DaytonaRecordingFfmpegNotFoundError(DaytonaServiceUnavailableError)

ffmpeg binary is not installed; required for recording.

error_class_from_status_code

def error_class_from_status_code(
        status_code: int | None) -> type[DaytonaError]

Map an HTTP status code to the corresponding DaytonaError subclass.

create_daytona_error

def create_daytona_error(message: str,
                         status_code: int | None = None,
                         headers: Mapping[str, Any] | None = None,
                         code: str | None = None,
                         source: str | None = None) -> DaytonaError

Create the appropriate DaytonaError subclass from structured error metadata.

Resolution order: (source, code) exact match → HTTP status code → base :class:DaytonaError.

DaytonaAuthorizationError

DaytonaAuthorizationError = DaytonaForbiddenError

Deprecated alias for :class:DaytonaForbiddenError. Kept so existing except DaytonaAuthorizationError blocks continue to work.

DaytonaValidationError

DaytonaValidationError = DaytonaBadRequestError

Deprecated alias for :class:DaytonaBadRequestError. Kept so existing except DaytonaValidationError blocks continue to work.