> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and limits

> Handle SDK errors and plan around current limits.

## Handle errors

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

```python Python theme={null}
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)
```

```go Go theme={null}
_, 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`.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.