Errors

Every failure in the Python SDK is raised as DaytonaError or one of its subclasses — named to match the official Daytona SDK so existing error handling ports unchanged. HTTP failures map onto subclasses by status code; client-side failures (validation, timeouts, connection errors) use the same classes.

Hierarchy

All classes are importable from rlp:

Python

from rlp import (
    DaytonaError,
    DaytonaValidationError,
    DaytonaAuthenticationError,
    DaytonaAuthorizationError,
    DaytonaNotFoundError,
    DaytonaConflictError,
    DaytonaRateLimitError,
    DaytonaTimeoutError,
    DaytonaConnectionError,
    DaytonaNotSupportedError,
)

Exception	HTTP status	Raised when
`DaytonaError`	any / none	Base class; also raised directly for unmapped statuses and generic failures (e.g. a sandbox landing in `error`).
`DaytonaValidationError`	400	Invalid input — server-side, or client-side (missing `api_url`, negative timeout, missing `snapshot`/`image`).
`DaytonaAuthenticationError`	401	Authentication failed, including a missing API key at client construction.
`DaytonaAuthorizationError`	403	Request forbidden.
`DaytonaNotFoundError`	404	Resource not found.
`DaytonaConflictError`	409	Resource conflict — e.g. deleting a volume that is still attached.
`DaytonaRateLimitError`	429	Rate limit exceeded.
`DaytonaNotSupportedError`	501	Operation not supported — e.g. `stop()`/`pause()`/`fork()` on a non-persistent sandbox, or `archive()`.
`DaytonaTimeoutError`	—	An HTTP request or a wait (e.g. `wait_until_started`) timed out.
`DaytonaConnectionError`	—	The network connection failed.

Every instance carries three attributes:

Attribute	Type	Description
`message`	`str`	Human-readable message (from the API's error body when available).
`status_code`	`int \| None`	HTTP status, when the error came from a response.
`error_code`	`str \| None`	Machine-readable code from the API body, when present.

Patterns

Handle a create timeout by inspecting and cleaning up the sandbox:

Python

from rlp import Daytona, CreateSandboxFromImageParams, DaytonaTimeoutError
 
daytona = Daytona()
try:
    sandbox = daytona.create(CreateSandboxFromImageParams(image="python:3.12-slim"), timeout=30)
except DaytonaTimeoutError:
    # The sandbox may still be booting; find it and decide whether to wait or delete.
    for sb in daytona.list():
        if sb.state in ("creating", "starting"):
            sb.wait_until_started(timeout=120)

Retry on rate limits:

Python

import time
from rlp import DaytonaRateLimitError
 
for attempt in range(5):
    try:
        result = sandbox.process.exec("make test")
        break
    except DaytonaRateLimitError:
        time.sleep(2 ** attempt)

Branch on capability — persistent-only operations raise DaytonaNotSupportedError locally:

Python

from rlp import DaytonaNotSupportedError
 
try:
    sandbox.stop()
except DaytonaNotSupportedError:
    # Not a persistent sandbox — there is no warm stop; delete instead.
    sandbox.delete()

Detect a spot-evicted sandbox: eviction pauses a persistent spot sandbox (or deletes an ephemeral one), so a stopped persistent spot sandbox can simply be started again. See spot sandboxes.

Python

sandbox.refresh_data()
if sandbox.state == "stopped":
    sandbox.start()  # warm-resume after eviction

Hierarchy

Patterns

On this page