Skip to content

sistemo.io ^beta

Error handling (Python)¶

All SDK exceptions subclass SistemoError.

from sistemo import (
    Sandbox,
    SistemoError,         # base class
    APIError,             # non-2xx (has .status, .detail, .code)
    AuthError,            # 401 / 403 — key missing, invalid, revoked, or read-only
    QuotaExceededError,   # 403 quota_exceeded — catch this BEFORE AuthError
    NotFoundError,        # 404
    RateLimitError,       # 429
    ExecStartUnconfirmed, # 503 on POST /execs — command MAY be running
    JobTimeout,           # client wait() gave up; the job is still running
)

Hierarchy¶

SistemoError
└── APIError(status, detail, code)
    ├── AuthError            (401, 403 forbidden)
    ├── QuotaExceededError   (403 quota_exceeded)  # NOT a subclass of AuthError
    ├── NotFoundError        (404)
    ├── RateLimitError       (429)
    └── ExecStartUnconfirmed (503 on POST /execs)
JobTimeout                   # wait()/stream() client timeout; job still running

SistemoError (not APIError) is also raised for client-side problems like a missing API key or a connection failure.

Handling specific cases¶

from sistemo import Sandbox, AuthError, QuotaExceededError, RateLimitError, APIError

try:
    with Sandbox() as sb:
        print(sb.run("uname -a").stdout)
except QuotaExceededError as e:
    print("quota:", e.detail)   # retry works once you free a machine/volume
except AuthError:
    print("Check SISTEMO_API_KEY — missing, revoked, or read-only.")
except RateLimitError:
    print("Rate limited — back off and retry.")
except APIError as e:
    print(f"API error {e.status}: {e.detail} ({e.code})")

Fields on `APIError`¶

Field	Example
`status`	`403`
`detail`	`"Machine quota exceeded (limit 1)."`
`code`	`"quota_exceeded"`

See API errors for the full list of code values.