Errors and limits

Handle errors

Errors returned by the service carry the HTTP status code and a message.

from agentbox_sdk import NotFoundError, APIError

try:
    client.agents.get("missing")
except NotFoundError as exc:
    print(exc.status_code, exc.message)
except APIError as exc:
    print(exc.status_code, exc.code, exc.message)

_, err := client.Agents.Get(ctx, "missing")
var apiErr *agentbox.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.StatusCode, apiErr.Code, apiErr.Message)
}
if agentbox.IsNotFoundError(err) {
	// handle 404
}

HTTP status	Python exception	Go check	Example cause
400	`BadRequestError`	`IsBadRequestError`	Resume `timeout_seconds` below 60
401	`AuthenticationError`	`IsAuthenticationError`	Invalid API key
403	`PermissionDeniedError`	`IsPermissionDeniedError`	No permission for the resource
404	`NotFoundError`	`IsNotFoundError`	Resource does not exist
409	`ConflictError`	`IsConflictError`	Snapshot of a paused sandbox; deleting an Agent that still has sandboxes
410	`GoneError`	`IsGoneError`	Build logs expired
413	`APIError` with `status_code` 413	`IsRequestTooLargeError`	Upload over the size limit
422	`UnprocessableError`	`IsUnprocessableError`	Sandbox Agent created without a data center or size
429	`RateLimitError`	`IsRateLimitError`	Too many requests
501	`NotSupportedError`	`IsNotSupportedError`	Operation not supported by this runtime
5xx	`ServerError`	`IsServerError`	Service error

Other errors:

Python	Go	When
`TransportError`	`*agentbox.TransportError`	The service could not be reached. In Go, also when reading the response failed
`SandboxFailed`	`*agentbox.SandboxFailed`	Waiting for `running` hit `error`, `deleted`, `stopped` or `stopping`
`SandboxWaitTimeout`	`*agentbox.SandboxWaitTimeout`	Waiting for `running` timed out
`SnapshotFailed`	`*agentbox.SnapshotFailed`	Waiting for a snapshot hit `error`, `deleting` or `delete_failed`
`SnapshotWaitTimeout`	`*agentbox.SnapshotWaitTimeout`	Waiting for a snapshot timed out

In Python, service and connection errors derive from AgentBoxSDKError, and every service error derives from APIError. Invalid input, such as a missing API key, a relative file path, or a missing idc_name or instance_type on launch, raises a plain ValueError.

The SDK does not retry failed requests. On rate-limit or server errors, retry with backoff.

Limits

Item	Current behavior	What to do
Sandbox start	A new sandbox is `pending` for a short time before `running`	Call `wait_until_running` before commands or file transfers
Default lifetime	24 hours if `timeout_seconds` is not set	Set `timeout_seconds` in tests; adjust with `set_timeout`
Command wait	A synchronous `execute` waits at most 25 seconds	Use `wait=False` and poll with `get_execution`
Command output	`stdout` and `stderr` each return at most 1 MiB	Write output to a file and download it
Upload size	About 500 MB per upload; larger returns 413	Split the file, or download it from inside the sandbox
Request timeout	30 seconds per request by default	Raise it for large files
Shell connections	One at a time per sandbox; `exit` ends the shell for good	Close the connection instead of running `exit`; use `execute` for parallel work
Paused sandboxes	Kept for up to 7 days, then deleted with their disk	Resume before `paused_expire_at`
Resource metrics	`metrics` and `metrics_timeseries` return 501 on sandboxes	Run `free -m`, `df -h` or `top -b -n1` with `execute`
Docker	Not available inside a sandbox	Contact GMI if you need Docker
Outbound IP	Shared data center egress address; some sites block cloud IPs	Contact GMI for an allowlist or a dedicated egress IP
Account balance	Without balance or credit, a sandbox stops a few seconds after launch	Top up or redeem credit

Reporting a problem

Send your GMI contact:

SDK language and version
Data center, size and image
Sandbox ID, and the execution ID for command issues
request_id and trace_id from the error response, if present, plus the HTTP status and message
Time of the issue (UTC)
The smallest code or command that reproduces it

Never include your API key.

GMI Agentbox

Agentbox SDK

Sandbox SDK

Sandbox APIs

Handle errors

Limits

Reporting a problem

​Handle errors

​Limits

​Reporting a problem

Handle errors

Limits

Reporting a problem