Skip to content

Protocol

Status Codes

How gRPC status codes and other outcomes on the wire become the SDK’s errors. The SDK errors are described on the Errors guide.

On the wire When SDK error
NOT_FOUND from GetSession the sandbox doesn’t exist (deleted, or a wrong name) SandboxNotFoundError / *NotFoundError (What: "sandbox") / Error::NotFound
RESOURCE_EXHAUSTED from CreateSession the sandbox limit is reached (one per user and three per organization during the beta) LimitReachedError / ErrLimitReached / Error::LimitReached
ABORTED “busy: the guest is held elsewhere … nothing ran” from Exec an interactive shell holds the sandbox and didn’t let go within 10 s SandboxBusyError / ErrBusy / Error::Busy
FAILED_PRECONDITION “instance held by another controller” or “Channel already in use” another attach or exec ended moments ago none: the SDK retries for about 30 s, then raises the error
FAILED_PRECONDITION “attach with a shell first to upload the workspace” Exec before the first attach none: the SDK always completes the first attach first
UNAUTHENTICATED the token is missing, expired or for another audience the SDK refreshes or logs in first, so this means the login can’t be used
Exec stream ends without exited the connection dropped mid-command OutcomeUnknownError / ErrOutcomeUnknown / Error::OutcomeUnknown (the command may have run)
exited.timed_out = true deadline passed; the service killed the process TimeoutError with the output so far
exited.code ≠ 0 the command failed CommandExitError with exit_code, stdout, stderr
exited.code 44, 45, 46 from an SDK script a missing path, a directory where a file was expected, or the reverse FileNotFoundError, InvalidPathError
exited.code 47 with “sandbox: no such directory” the command’s cwd doesn’t exist FileNotFoundError / *NotFoundError (What: "directory") / Error::NotFound
HTTP 400 “invalid refresh token: refresh token expired at …” from the issuer the saved login is older than 20 hours none: the SDK logs in again (or fails with a “login required” error when CHAINGUARD_SANDBOX_NO_BROWSER=1)

Any other status: Go returns the gRPC status error as-is (read it with status.Code(err)), Rust returns Error::Rpc with the status (and grpc_code()), and Python and TypeScript raise SandboxError with the code and message ("UNAVAILABLE: …").