snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/egress.py

@@ -0,0 +1,388 @@
+"""Outbound network policy — the ``Egress`` spec.
+
+``compile_egress`` folds brokered `Secret` entries into the egress object, since
+secrets are authored flat but nest on the wire. Host-pattern matching lives in
+`snowflake.sandbox._hosts`.
+
+    from snowflake.sandbox import Egress, compile_egress
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+
+from snowflake.sandbox.exceptions import SandboxError
+from snowflake.sandbox.secret import Secret, validate_secret_entries
+
+__all__ = ["Egress", "compile_egress"]
+
+
+_HOST_LIST_WIRE_KEY = "allowed_domains"
+
+_HOST_LIST_PARAM = "allowed_egress_hosts"
+
+# Spellings accepted on the raw-dict path, all normalized to the wire key. The typed
+# constructor takes only _HOST_LIST_PARAM; the others get a pointed error.
+_HOST_LIST_KEYS = (_HOST_LIST_PARAM, "allowed_hosts", _HOST_LIST_WIRE_KEY)
+
+
+def _retired_host_list_message(spelling: str) -> str:
+    """Guidance for the retired caller-supplied host list.
+
+    The platform reserved this field server-side and removed the grant
+    *silently*: hosts named there now land in unknown fields and are dropped,
+    emitting only a server-side warning the caller never sees. The sandbox comes
+    up healthy and simply cannot reach the hosts the caller believes it allowed,
+    and nothing on the request path says so.
+
+    That silence is the whole reason this raises instead of warning: a client-side error
+    is the only place the caller can still learn, and a sandbox that quietly cannot
+    reach its dependency is worse than one that refuses to start.
+    """
+    return (
+        f"egress {spelling}= is no longer supported: Snowflake retired the "
+        f"caller-supplied host list, so hosts named here are IGNORED — not enforced, "
+        f"and not reachable. The request still succeeds, which is why this fails "
+        f"locally instead: the sandbox would start healthy and silently fail to reach "
+        f"them.\n\n"
+        f"Grant the hosts with an External Access Integration and name it instead:\n"
+        f'    Egress(allow_default_egress=False, external_access_integrations=("MY_EAI",))\n\n'
+        f"Creating one (the network rule cannot live in a personal USER$ database):\n"
+        f"    CREATE NETWORK RULE db.schema.my_rule MODE = EGRESS TYPE = HOST_PORT\n"
+        f"        VALUE_LIST = ('example.com:443');\n"
+        f"    CREATE EXTERNAL ACCESS INTEGRATION my_eai\n"
+        f"        ALLOWED_NETWORK_RULES = (db.schema.my_rule) ENABLED = TRUE;\n"
+        f"    GRANT USAGE ON INTEGRATION my_eai TO ROLE <the role that creates sandboxes>;"
+    )
+
+
+def _nonempty_host_value(raw: object) -> bool:
+    """Whether a host-list value would contribute any hosts.
+
+    Only decides whether a value would contribute hosts — it deliberately does not
+    validate the entries, because a non-empty list is refused outright now (the platform
+    retired the field), so there is nothing left to validate it against. A non-sequence
+    counts as non-empty so a malformed value is refused rather than silently ignored.
+    """
+    if isinstance(raw, str) or not isinstance(raw, Sequence):
+        return True
+    return len(raw) > 0
+
+
+# The REST spelling of the default-egress tri-state. Named once: the SDK parameter was
+# renamed to allow_default_egress, the wire key was not, and two places translate between
+# them (Egress.to_wire and compile_egress's raw-dict path).
+_DEFAULT_EGRESS_WIRE_KEY = "allow_internet"
+
+
+@dataclass(frozen=True)
+class Egress:
+    """Controls outbound network access from the sandbox.
+
+    Pass as `egress=` to `Sandbox.create()` or `@app.function`.
+
+    There are exactly three levels of access, and the middle one is the default:
+
+    | level | how | reaches |
+    |---|---|---|
+    | baseline | the default, or `allow_default_egress=True` | Snowflake, the cloud-storage stages, and ~43 package-manager hosts |
+    | closed | `allow_default_egress=False` / `Egress.only()` | Snowflake and its stages only |
+    | granted | `external_access_integrations=(...)` | the above, plus whatever the EAI's network rules resolve to |
+
+    **The baseline is not the internet.** It is a curated host set the platform
+    maintains; anything outside it is refused, so a host you need that is not on that
+    list requires an External Access Integration whichever level you pick. A
+    caller-supplied host list used to be the third option and is now retired.
+
+    `allow_internet` is the former name of `allow_default_egress` and still works, with a
+    DeprecationWarning. It was misleading in both directions: it never granted the whole
+    internet, and False does not stop egress because an EAI still grants.
+
+    Example:
+        egress = Egress()                                # baseline
+        egress = Egress.only()                           # closed: nothing arbitrary
+        egress = Egress(allow_default_egress=False, external_access_integrations=("MY_EAI",))
+
+    `allow_github` and `allow_pypi` are both **deprecated and inert**. `allow_internet` is
+    the only egress control. Public PyPI is already reachable via the package-managers
+    group, and the six GitHub/dbt hosts now need an External Access Integration like any
+    other host outside that group. Both flags will be removed in a future release.
+    """
+
+    # Tri-state, and only one of the three states does anything: None (unset) and True
+    # both leave the platform in baseline mode, because sandbox-api sets
+    # disallow_non_snowflake_access ONLY when this is explicitly False. So False is the
+    # single value that changes behaviour — it closes egress, which also withholds the
+    # baseline and disables the group flags below.
+    allow_internet: bool | None = None
+    # Deprecated and inert. It set EgressConfig.allow_egress_to_github_and_dbt, the six-host
+    # GitHub/dbt group, which the platform is removing — leaving allow_internet as the only
+    # egress control. Those hosts need an External Access Integration now. Setting it does
+    # nothing and, unlike allow_pypi, does not even warn (see __new__); to_wire() no longer
+    # sends it. Retained and still defaulting True, so existing callers keep constructing
+    # without a TypeError and no value of it reads as meaningful; remove in a later major.
+    allow_github: bool = True
+    # Deprecated and inert. It once set StartAppRequest.allow_artifact_repository_pypi,
+    # which the platform reserved in favour of a different mechanism (a pip.conf routed
+    # to a Snowflake Artifact Repository) that is not expressible here. It never governed
+    # public PyPI — pypi.org and files.pythonhosted.org are in the always-on
+    # package-managers group, reachable by default with no flag. Setting it does nothing;
+    # __post_init__ warns and to_wire() no longer sends it. Retained (not deleted) so
+    # existing callers keep constructing without a TypeError; remove in a later major.
+    allow_pypi: bool = False
+    external_access_integrations: tuple[str, ...] = field(default_factory=tuple)
+    # The preferred spelling of allow_internet, which was misleading in both directions:
+    # it never granted "the internet" (the baseline is a curated ~43-host set), and False
+    # does not stop egress (an EAI still grants). Tri-state exactly like the field it
+    # replaces. Appended last so positional Egress(None, True, False, (...)) callers are
+    # unaffected. The WIRE key is still allow_internet — this is a client-side rename, so
+    # no server change is needed and old and new SDKs interoperate.
+    allow_default_egress: bool | None = None
+
+    def __post_init__(self) -> None:
+        # A dataclass enforces no types, so Egress(allow_internet="false") kept the string and
+        # reached the wire, where the server's `*bool` refused it with a Go type name. Checked
+        # here so it raises at the call the caller wrote. allow_internet is tri-state (None).
+        for name, nullable in (
+            ("allow_internet", True),
+            ("allow_default_egress", True),
+            ("allow_github", False),
+            ("allow_pypi", False),
+        ):
+            value = getattr(self, name)
+            if value is None and nullable:
+                continue
+            if not isinstance(value, bool):
+                raise SandboxError(
+                    f"Egress({name}=) must be True or False, got {type(value).__name__} {value!r}"
+                )
+        # Both spellings set and disagreeing is ambiguous, and picking one silently would
+        # apply an egress posture the caller did not ask for. Raise at the call instead.
+        if (
+            self.allow_internet is not None
+            and self.allow_default_egress is not None
+            and self.allow_internet != self.allow_default_egress
+        ):
+            raise SandboxError(
+                "Egress(allow_internet=) and Egress(allow_default_egress=) disagree "
+                f"({self.allow_internet!r} vs {self.allow_default_egress!r}). They are the "
+                "same control — pass only allow_default_egress."
+            )
+        # NOT warned on deliberately. The suite runs filterwarnings=error, so emitting a
+        # DeprecationWarning here fails all 21 tests that construct Egress(allow_internet=)
+        # -- the old name still works and still reaches the wire, so the warning buys a
+        # large test migration for no behaviour change. Add it, with that migration, in the
+        # release that removes the old name.
+        # allow_pypi is deprecated and inert (see the field comment). Warn rather than
+        # raise: it reaches no server behaviour, so a costless no-op should not break a
+        # working sandbox — but the caller should stop relying on it. This is the one
+        # place a positional Egress(None, True, True, ...) is also caught.
+        if self.allow_pypi:
+            warnings.warn(
+                "Egress(allow_pypi=...) is deprecated and has no effect. Public PyPI "
+                "(pypi.org, files.pythonhosted.org) is already reachable by default via "
+                "the package-managers group, so no flag is needed; routing to a Snowflake "
+                "Artifact Repository is not expressible today. Remove allow_pypi; it will "
+                "be dropped in a future release.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+
+    @staticmethod
+    def only() -> Egress:
+        """Close egress — ``Egress.only()``, with no arguments.
+
+        Sets ``allow_default_egress=False``, which withholds the platform baseline as well: no
+        arbitrary internet host is reachable, not even the package-manager set the default
+        mode grants. Snowflake and its stages stay reachable regardless — see the danger
+        note below, which is why this is not described as total confinement.
+
+        It takes **no arguments**. Naming hosts to allow back is gone with the retired
+        caller-supplied host list; to confine and then grant a specific host, pair
+        confinement with an External Access Integration:
+
+            Egress(allow_default_egress=False, external_access_integrations=("MY_EAI",))
+
+        !!! danger "Not an exfiltration boundary for Snowflake destinations"
+            ``only()`` does **not** confine the sandbox to *just* a chosen set of hosts.
+            Egress to **Snowflake itself and to the cloud-storage stages** backing the
+            sandbox stays open regardless — it is the control plane the sandbox runs on, and
+            `get_snowflake_connection()` always has a working credential inside the
+            container. So a workload can still write data to a Snowflake table or a stage it
+            can reach even under `Egress.only()`. Treat this as *"which arbitrary
+            internet hosts may I reach"*, **not** *"data cannot leave"*: it is not a
+            data-exfiltration boundary against a Snowflake-reachable destination.
+
+            Reachability is also not the same as credential scope — a granted host does not
+            get a credential, and a `Secret`'s ``host`` is itself a grant, not a
+            restriction. See *Reachability is not credential scope* above and the
+            ``Secret`` docs.
+        """
+        # New spelling deliberately: only() must not emit a DeprecationWarning at a
+        # caller who never touched the old name.
+        return Egress(allow_default_egress=False)
+
+    @property
+    def default_egress_allowed(self) -> bool | None:
+        """The effective tri-state, whichever spelling the caller used.
+
+        Read this rather than either field: a caller who set only the new name must not
+        look "unset" to logic that checks the old one, which is the bug a plain alias
+        would introduce.
+        """
+        if self.allow_default_egress is not None:
+            return self.allow_default_egress
+        return self.allow_internet
+
+    def to_wire(self) -> dict[str, object]:
+        """This scope as the ``egress`` request body, without secrets.
+
+        Use `compile_egress()` to fold a sandbox's ``secrets=`` in.
+        """
+        body: dict[str, object] = {}
+        effective = self.default_egress_allowed
+        if effective is not None:
+            # Sent even when False: the platform reads an absent key as its permissive
+            # default, so omitting it would silently discard a request to close egress.
+            # The key stays allow_internet — the rename is client-side only.
+            body[_DEFAULT_EGRESS_WIRE_KEY] = effective
+        # Neither group flag is sent: the platform is removing the GitHub/dbt flag and already
+        # reserved the one allow_pypi fed, so either would describe a grant that never happens.
+        # Both stay accepted on the way in (see the field comments).
+        # No host-list key is ever sent: allowed_egress_hosts was removed from Egress (a
+        # caller-supplied host list is retired platform-side). The raw egress={...} dict
+        # path still refuses the wire spellings in compile_egress().
+        if self.external_access_integrations:
+            body["external_access_integrations"] = self._validated_eais()
+        return body
+
+    def _validated_eais(self) -> list[str]:
+        """EAI names, shape-checked and deduped the way the platform dedupes them.
+
+        The platform compares EAI names *unqualified*, so ``DB.SCHEMA.X`` and ``X``
+        are the same integration and a repeat is a hard error there.  Rejecting it
+        here gives a clearer message than the remote one.
+        """
+        out: list[str] = []
+        seen: dict[str, str] = {}
+        for raw in self.external_access_integrations:
+            name = raw.strip()
+            if not name:
+                raise SandboxError("external_access_integrations contains an empty name")
+            if any(c in name for c in "/: \t"):
+                raise SandboxError(
+                    f"external access integration {name!r} must be a bare name — "
+                    f"'MY_EAI' or 'DB.SCHEMA.MY_EAI', with no scheme, port, or path"
+                )
+            key = name.rsplit(".", 1)[-1].upper()
+            if key in seen:
+                raise SandboxError(
+                    f"external access integrations {seen[key]!r} and {name!r} are the same "
+                    f"integration: names are compared unqualified, so 'DB.SCHEMA.X' and 'X' "
+                    f"collide"
+                )
+            seen[key] = name
+            out.append(name)
+        return out
+
+
+def compile_egress(
+    egress: Egress | Mapping[str, object] | None,
+    secrets: Sequence[Secret | Mapping[str, object]] = (),
+) -> dict[str, object] | None:
+    """Fold *secrets* into *egress* to build the request's ``egress`` object.
+
+    Secrets are authored flat but nest on the wire, since ``egress.secrets`` is a
+    field of Snowflake's egress config.  A plain dict is accepted for the imperative
+    path (and may already carry ``secrets``).
+
+    Passing ``egress=None`` means "use the defaults" rather than "send nothing", though
+    the two now coincide: the only meaningful field is the default-egress tri-state, whose
+    default is the platform's own, so a default `Egress` serialises to nothing. A dict is
+    taken as authored, since that path is the raw-wire escape hatch — except that
+    ``allow_default_egress`` is translated to the wire key, because a raw-dict caller who
+    used the name the docs now teach would otherwise have it silently ignored.
+    """
+    if isinstance(egress, Egress):
+        body = egress.to_wire()
+    elif egress is None:
+        body = Egress().to_wire()
+    else:
+        body = dict(egress)
+        # A raw dict is otherwise passed through verbatim, which would make
+        # {"allow_default_egress": False} a silent no-op: the server sees no
+        # allow_internet key and applies its PERMISSIVE default, so a caller asking to
+        # close egress would get the baseline instead. Translate to the wire key rather
+        # than refuse, matching what the typed path accepts.
+        if "allow_default_egress" in body:
+            renamed = body.pop("allow_default_egress")
+            existing = body.get(_DEFAULT_EGRESS_WIRE_KEY)
+            if existing is not None and renamed is not None and existing != renamed:
+                raise SandboxError(
+                    f"egress dict sets both {_DEFAULT_EGRESS_WIRE_KEY!r} and "
+                    f"'allow_default_egress' to different values ({existing!r} vs "
+                    f"{renamed!r}). They are the same control — pass one."
+                )
+            if renamed is not None:
+                body[_DEFAULT_EGRESS_WIRE_KEY] = renamed
+        # Two spellings of the host list in one dict is refused rather than resolved.
+        # The normalizing loop below writes into _HOST_LIST_WIRE_KEY, which is also
+        # the last key it reads, so an earlier alias used to overwrite a later one's
+        # value before that value was ever read: {allowed_egress_hosts: [a],
+        # allowed_domains: [b]} silently compiled to [a], and which alias won was an
+        # artifact of pop-and-overwrite ordering rather than a precedence anyone
+        # chose ('allowed_hosts' beat 'allowed_egress_hosts', which beat
+        # 'allowed_domains'). On an egress allowlist, quietly enforcing a narrower
+        # host set than the caller wrote is the one outcome worth failing over, so
+        # ambiguity is an error and the caller picks a spelling.
+        #
+        # Only non-empty values count: an alias mapped to [] contributes no hosts, so
+        # `{allowed_egress_hosts: [], allowed_domains: [...]}` loses nothing and is a
+        # normal result of merging a default with an override.
+        present = [k for k in _HOST_LIST_KEYS if k in body and _nonempty_host_value(body[k])]
+        if len(present) > 1:
+            raise SandboxError(
+                f"egress carries more than one spelling of the host list "
+                f"({', '.join(repr(k) for k in present)}), and they would not all be "
+                f"applied. Pass exactly one — {_HOST_LIST_PARAM!r} is the blessed name "
+                f"(the REST wire key stays {_HOST_LIST_WIRE_KEY!r}). If these came from "
+                f"different config sources, merge them into one list first."
+            )
+        # The raw-dict path is the wire escape hatch, so it accepts all three spellings —
+        # and therefore has to refuse all three now that the field is retired. Dropping
+        # the key silently would be the worst option available: this path exists precisely
+        # for callers pinning wire details, who are the least likely to notice a host list
+        # quietly vanishing. An empty value is still tolerated and simply removed, so
+        # merging a default over an override keeps working.
+        for key in _HOST_LIST_KEYS:
+            if key in body:
+                raw = body.pop(key)
+                if _nonempty_host_value(raw):
+                    raise SandboxError(_retired_host_list_message(key))
+
+    # `body` is loosely typed (it may be a caller-supplied dict), so narrow the
+    # nested secrets list explicitly before iterating it.
+    existing = body.pop("secrets", None)
+    entries: list[dict[str, object]] = []
+    if isinstance(existing, Sequence) and not isinstance(existing, (str, bytes)):
+        entries.extend(dict(e) for e in existing if isinstance(e, Mapping))
+    for s in secrets:
+        entries.append(dict(s.to_wire()) if isinstance(s, Secret) else dict(s))
+
+    if entries:
+        validate_secret_entries(entries)
+        # Brokered secrets ride ``egress.secrets``, which is Snowflake's DEPRECATED
+        # egress-config secrets field. On a reconstruction (idle-resume / restart /
+        # replica reroute) the controller re-launches the app from its stored app
+        # record, which carries no egress config at all — so these secrets are
+        # dropped and the sandbox comes back without them. That record does have a
+        # secrets field of its own, but it is a *file-mount* shape
+        # ({secret_name, mount_relative_path}), not the brokered
+        # {fqn, allowed_host, env_var} shape, so no reconstruction-surviving
+        # brokered-secret path exists server-side yet. The SDK therefore keeps this
+        # wire additive and does NOT emit a speculative top-level field, which the
+        # service would either ignore or misread as file-mount secrets.
+        body["secrets"] = entries
+    return body or None

snowflake/sandbox/exceptions.py

@@ -0,0 +1,253 @@
+"""Exception hierarchy for ``snowflake.sandbox``.
+
+All errors derive from ``SandboxError`` so callers can ``except SandboxError``
+to catch any SDK failure. Cancellation is intentionally NOT wrapped —
+``asyncio.CancelledError`` propagates as-is (see ``_transport.py``).
+
+These classes are pure-Python and import-cheap (no httpx, no pydantic), so
+``snowflake.sandbox.__init__`` re-exports them eagerly.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "SandboxError",
+    "SandboxAuthError",
+    "SandboxNotFoundError",
+    "SandboxNotReadyError",
+    "SandboxNotImplementedError",
+    "SandboxValidationError",
+    "SandboxConflictError",
+    "SandboxExecError",
+    "SandboxExecTimeoutError",
+    "SandboxRateLimitError",
+    "SandboxTransportError",
+    "SandboxFileTooLargeError",
+    "SandboxContractWarning",
+]
+
+
+class SandboxContractWarning(UserWarning):
+    """The server sent something this SDK does not understand.
+
+    Emitted instead of silently guessing. Unknown JSON keys are ignored on the
+    wire in both directions, so an old server answering a new client (or the
+    reverse) otherwise produces a *wrong* value with a 200 and no signal at all
+    -- a container reported ``ready`` because its real status was unrecognized,
+    or a 64g sandbox reported as the 4g default. Warned, never inferred.
+    """
+
+
+def _rebuild_sandbox_error(
+    cls: type[BaseException], args: tuple[object, ...], state: dict[str, object]
+) -> BaseException:
+    """Reconstruct a `SandboxError` (or subclass) during unpickling.
+
+    Bypasses ``__init__`` -- restoring ``args`` and instance ``__dict__``
+    directly -- so a subclass with **kw-only** constructor arguments round-trips.
+    The default ``BaseException`` reducer reconstructs via ``cls(*self.args)``,
+    which drops every keyword-only field: ``SandboxExecError``'s required
+    ``exit_code`` then raises ``TypeError`` on unpickle, and
+    ``SandboxRateLimitError``'s ``retry_after`` would silently reset to its
+    default. See `SandboxError.__reduce__`.
+    """
+    obj = cls.__new__(cls)
+    obj.args = args
+    obj.__dict__.update(state)
+    return obj
+
+
+class SandboxError(Exception):
+    """Base class for every error raised by ``snowflake.sandbox``.
+
+    ``except SandboxError`` catches every SDK-raised error.
+
+    Remediation: Catch the specific subclass that applies to your situation
+    for precise handling, and use ``except SandboxError`` only as a
+    catch-all fallback.
+    """
+
+    def __reduce__(
+        self,
+    ) -> tuple[object, ...]:
+        # Make every SDK error picklable, including the subclasses whose __init__
+        # takes keyword-only arguments (SandboxExecError.exit_code,
+        # SandboxRateLimitError.retry_after). The default reducer replays
+        # ``cls(*self.args)``, which cannot supply a kw-only field -- a required
+        # one (exit_code) then raises TypeError on unpickle, breaking any transport
+        # that pickles exceptions across a process boundary (ProcessPool, Celery,
+        # Ray, Airflow). Rebuild via __new__ + state instead so all fields survive.
+        return (_rebuild_sandbox_error, (type(self), self.args, self.__dict__.copy()))
+
+
+class SandboxAuthError(SandboxError):
+    """HTTP 401/403 from the Cortex Sandboxes service.
+
+    Remediation: Verify your Snowflake connection is configured and
+    authenticated, and that your role has permission to create sandboxes.
+    """
+
+
+class SandboxNotFoundError(SandboxError):
+    """HTTP 404 — container or resource missing.
+
+    Remediation: The sandbox id is invalid or the sandbox was already
+    terminated. Re-create it.
+    """
+
+
+class SandboxNotReadyError(SandboxError):
+    """Container not ready: HTTP 409 cold-start exhausted, or async create timed out.
+
+    Raised either when the server returns HTTP 409 after the retry budget is
+    exhausted (cold-start), or when ``Sandbox.create()`` / ``wait_until_ready()``
+    polling does not see the container become live within the timeout window.
+
+    Remediation: Wait a moment and retry, or increase the ``timeout=`` passed to
+    ``wait_until_ready()``.
+    """
+
+
+class SandboxValidationError(SandboxError):
+    """HTTP 400 — the request parameters are invalid.
+
+    The server rejected the request because something in it was malformed or
+    violated a constraint. Common causes include: a reserved environment variable
+    name (SNOWFLAKE_*, SANDBOX_*), an invalid image name, a malformed egress
+    configuration, or a missing required field.
+
+    Remediation: Check the error message for which parameter is invalid.
+    The message usually includes the specific field and why it was rejected.
+    """
+
+
+class SandboxConflictError(SandboxError):
+    """HTTP 409 — the resource already exists or is in a conflicting state.
+
+    A name collision, a duplicate create, or an operation that conflicts with
+    the resource's current state. Unlike ``SandboxNotReadyError`` (which is a
+    transient cold-start condition the SDK retries internally), this is a
+    genuine conflict that won't resolve on retry.
+
+    Remediation: Use a unique name, connect to the existing sandbox instead
+    of creating a new one, or wait for the conflicting operation to complete.
+    """
+
+
+class SandboxNotImplementedError(SandboxError):
+    """A surfaced SDK method has no backend and will not until one lands.
+
+    Raised by the not-yet-implemented stubs (``snapshot_*``,
+    ``mount_image``/``unmount_image``, ``tunnels``, ``create_connect_token``) so an
+    unsupported call is *distinguishable* from an operational failure — a bare
+    ``SandboxError`` conflates "not built" with "transiently broke", and the
+    base-class docstring tells callers to ``except SandboxError``. This is a
+    permanent "not supported here", not a retryable condition: catching it and
+    retrying loops forever against a feature that is never coming.
+
+    It subclasses ``SandboxError`` so existing ``except SandboxError`` handlers
+    still catch it. The alternative — deriving from the stdlib
+    ``NotImplementedError``, outside the ``SandboxError`` tree — would stop a
+    broad ``except SandboxError: retry()`` from ever catching an unimplemented
+    call, but at the cost of escaping the catch-all handlers that today expect
+    every SDK error under ``SandboxError``.
+
+    Remediation: Remove the unsupported parameter or feature flag from your
+    code. This is not a transient failure — retrying will not help.
+    """
+
+
+class SandboxFileTooLargeError(SandboxError):
+    """A file transfer exceeded the size the platform will carry.
+
+    Raised locally before the request when the caller's file is over the limit, and
+    on a 413 from the server. The ceiling is not the sandbox's: Snowflake's REST
+    front end caps request bodies well below any interesting file size, so bulk data
+    goes through a mounted stage rather than this path.
+
+    Remediation: Split the file into smaller chunks or upload via a Snowflake
+    stage and mount it instead.
+    """
+
+
+class SandboxExecError(SandboxError):
+    """Non-zero exit from ``Sandbox.exec``. Carries stdout/stderr/exit_code.
+
+    Remediation: Inspect ``exception.exit_code``, ``exception.stdout``, and
+    ``exception.stderr`` to diagnose the command failure.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        exit_code: int,
+        stdout: str = "",
+        stderr: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.stdout = stdout
+        self.stderr = stderr
+
+    def __str__(self) -> str:
+        parts = [super().__str__()]
+        if self.stderr:
+            parts.append(f"stderr: {self.stderr[:2000]}")
+        elif self.stdout:
+            parts.append(f"stdout: {self.stdout[:2000]}")
+        return "\n".join(parts)
+
+
+class SandboxExecTimeoutError(SandboxError):
+    """The server enforced its exec deadline, killing the command.
+
+    ``stdout``/``stderr`` carry the partial output the server returns on a timeout --
+    how a caller tells "the work started" from "it never did". All three fields are
+    optional: the transport also raises this for a 408 with no parsed body.
+
+    Remediation: inspect ``exception.stdout``/``exception.stderr`` to see how far the
+    command got, then raise ``timeout=``. For a long-lived process ``exec`` is the
+    wrong tool -- see ``Sandbox.create(command=...)``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        exit_code: int | None = None,
+        stdout: str = "",
+        stderr: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.stdout = stdout
+        self.stderr = stderr
+
+    def __str__(self) -> str:
+        parts = [super().__str__()]
+        if self.stderr:
+            parts.append(f"stderr: {self.stderr[:2000]}")
+        elif self.stdout:
+            parts.append(f"stdout: {self.stdout[:2000]}")
+        return "\n".join(parts)
+
+
+class SandboxRateLimitError(SandboxError):
+    """HTTP 429 after the SDK retry budget.
+
+    Remediation: Check ``exception.retry_after`` for the recommended wait
+    time before retrying, or reduce request concurrency.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class SandboxTransportError(SandboxError):
+    """5xx, DNS, connection, or read-timeout failures after retries.
+
+    Remediation: Check network connectivity and Snowflake service status,
+    then retry.
+    """