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: …").
