Errors

Enforcement lives in the browser binary; when it refuses to start, the SDK translates the failure into a precise, typed exception you can catch.

Exception	Raised when	Fix
CapiumError	Base class for every capium SDK error.	Catch this to handle any capium-specific failure.
CapiumLicenseError	The browser refused to start for a licensing reason (base for the four below).	Run capium status to see which.
CapiumConfigError	No license key configured.	Set CAPIUM_LICENSE_KEY, pass license_key=, or create ~/.capium/license (KEY=).
CapiumSeatLimitError	Concurrent session limit reached across your machines.	Close another Capium browser and retry, or upgrade your plan.
CapiumExpiredError	License expired, revoked, or the key is invalid.	Check your subscription and key on the capzy.ai dashboard.
CapiumServerDownError	License service unreachable and no valid offline grace.	Check the host's egress/firewall to license.capzy.ai.

All inherit from CapiumError, and the four licensing ones from CapiumLicenseError, so you can catch broadly or narrowly.

Handling them

handle.py

from capium import launch_context, CapiumSeatLimitError, CapiumExpiredError

try:
    browser, ctx, page = launch_context(seed=200123, url="https://example.com")
except CapiumSeatLimitError:
    ...   # too many concurrent browsers — close one or upgrade
except CapiumExpiredError:
    ...   # key invalid / expired / revoked

For step-by-step fixes see Troubleshooting.

Command-line

Troubleshooting