---
title: "Limits, errors, and unsupported features"
description: "Public API input limits and HTTP failure behavior."
---

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

# Limits, errors, and unsupported features

These limits are enforced by the public v2 API:

| Input | Limit or default |
| --- | --- |
| JSON request body | 128 KiB maximum |
| Workspaces per account | 10 |
| Sandbox account capacity | Account-specific Sandbox-count and workspace-storage limits; stopped Sandboxes count toward both |
| Workspace name | 1–80 characters and must contain a non-whitespace character |
| Sandbox name | 1–80 characters when supplied |
| Sandbox size | VM-only string `small` or `large`; defaults to `small` |
| `Idempotency-Key` | 1–255 visible ASCII characters for ordinary mutations; required to create a workspace, explicitly request `vmSandbox: true`, or start an operation; optional when the VM selector is omitted or when starting an existing Sandbox; successful responses replay for 24 hours. Selected TCP service create/lookup instead require the same lowercase UUIDv4 operation key |
| VM Sandbox beta | New creation is VM-only: omitted `vmSandbox` (or `true`) creates a VM; `false` returns `400 INVALID_REQUEST`. `size` selects `small` (default, 0.5 vCPU / 1,024 MiB) or `large` (1.5 vCPU / 3,072 MiB); both default to a 30 GiB thin-provisioned workspace, no automatic lifetime expiry, and no libraries or shared volumes. `blockNetwork` defaults to false (outbound public IPv4 and DNS); `true` creates no network interface |
| Continuous VM uptime | Maintenance sleep is requested after about 42 hours, even with activity; idle sleep can happen sooner. Disk and Sandbox are retained, but processes and connections stop. Resume the same Sandbox; no automatic expiry is not an uptime guarantee |
| `argv` | 1–64 non-empty strings |
| Each `argv` entry | 8,192 characters maximum |
| `cwd` | `/workspace` or a path below it; defaults to `/workspace` |
| Environment | 64 variables maximum; string values and valid variable names |
| Execution timeout | 1–900 whole seconds; defaults to 120 |
| Synchronous or retained operation output | `maxOutputBytes` is 1–1,048,576 bytes per stream; defaults to 262,144 |
| Operation wait | 0–30 whole seconds; defaults to 30 |
| Operation output page | 1–262,144 decoded bytes; defaults to 65,536 |
| Terminal operation retention | 24 hours, including up to `maxOutputBytes` from each stream |
| File path | `/workspace` or a path below it, without `.` or `..` segments; 4,096 characters maximum |
| Log query entries | 1–5,000; defaults to 1,000 |
| Deleted Sandbox history | Up to 100 newest records returned; records retained about 15 months; no compute, storage or restore controls |
| Deleted Sandbox logs | Same 1–5,000-entry filters as current logs; available only within provider log retention, nominally about 30 days |
| File range read | 8 MiB maximum per response; `offset` defaults to 0 and `maxBytes` defaults to 8 MiB |
| File write or conditional edit | 8 MiB maximum complete file |
| Conditional file edit | Complete file must be UTF-8; `oldText` is 1–65,536 characters and `newText` is 0–65,536 characters |
| Directory listing page | 1–1,000 immediate entries; `pageSize` defaults to 1,000 |
| File continuation cursor | Opaque, path-bound, and 4,096 characters maximum |
| VM browser preview | One active HTTP/WebSocket tunnel per owned running network-enabled VM; one selected port from 1–65,535; fixed lifetime of at most one hour |
| VM browser preview URL | Random bearer capability; application restarts preserve the URL and original deadline, reopening only while the VM is running. Reconnect interrupted requests/WebSockets; explicit close, expiry, VM stop or guest tunnel loss can end the link. Public v2 has no keep-open or always-on controls; no UDP, SSH or general ingress |
| Cooperative connection grant | Operator-selected preview only; one nonrenewable grant lasting at most 30 seconds |
| Cooperative connection keys | Exact `client_key`, `ssh_key`, and `recipient_key` formats from OpenAPI; no extra fields |
| Cooperative sealed envelope | Base64, 80–16,000 characters |
| Selected TCP service grant | Generally enabled for an authenticated owner of an active VM; exactly one hour from `requested_at`, without renewal |
| Selected TCP service ports | 1–8 unique TCP ports from 1–65,535 in strictly ascending order; no UDP or public listener |
| Selected TCP service request | Current Unix-second `requested_at`, one nonzero Tailcat `client_key`, one canonical base64 32-byte `recipient_key`, and no extra fields |
| Selected TCP sealed envelope | Base64, 80–16,000 characters; create is not mutation-retryable, and exact lookup recovers only the original live envelope |
| Usage window | `days` is bounded to 1–90; defaults to 30 |
| Wallet transaction page | 1–200 newest-first entries; `limit` defaults to 50; pass `nextCursor` as `before` |
| Wallet transaction filters | Inclusive `from` and exclusive `to` RFC 3339 timestamps; `kind` is 1–64 characters, `bucket` is `cash`, `promo`, or `plan`; `before` is an opaque cursor of at most 512 characters |
| Sandbox cost-report window | Inclusive `from` and exclusive `to` RFC 3339 timestamps; defaults to the last 30 days and can span at most 400 days |
| Sandbox cost detail | Up to 1,000 settled runs; `truncated` reports omitted additional runs |
| Sandbox analytics resolution | 60–86,400 whole seconds; defaults to 300 |
| Sandbox analytics rate limit | 30 requests per minute per account |
| Sandbox analytics retention | 30 days |
| Audit event page | 1–200 newest-first events; defaults to 50; opaque cursor pagination |
| Audit event retention | `GET` and `HEAD` requests for 31 days; writes and key lifecycle events for about 15 months |
| Audit CSV export | Up to 10,000 matching rows from the web activity view |

Errors include a stable machine-readable `code` and a human-readable `error`
string:

```json
{ "code": "NOT_FOUND", "error": "Sandbox not found" }
```

Existing integrations may continue reading `error`; branch on `code`. Clients
must tolerate new codes added for compatible v2 routes.

| Status | Meaning |
| --- | --- |
| `400` | `INVALID_REQUEST` for invalid input or new gVisor creation (`vmSandbox: false`), `INVALID_PATH` for an unsafe file path, `INVALID_RANGE` for an invalid file offset, `INVALID_CURSOR` for invalid continuation, `BINARY_FILE` for a non-UTF-8 edit, or `INVALID_IDEMPOTENCY_KEY` for a missing or malformed required key |
| `401` | Missing, malformed, unknown, or revoked bearer key |
| `402` | `INSUFFICIENT_CREDIT` because BoxCompute credit is exhausted |
| `403` | `INSUFFICIENT_SCOPE` because the key does not include the route's required scope, or `BILLING_ACCOUNT_FROZEN` because the billing account is frozen |
| `404` | The active or deleted Sandbox, owned workspace, or requested file was not found |
| `408` | Execution timed out at the Sandbox service |
| `409` | `IDEMPOTENCY_CONFLICT` for conflicting key reuse, `WORKSPACE_QUOTA_EXCEEDED` at 10 workspaces, `DESTINATION_EXISTS` for a rename collision, `EDIT_CONFLICT` when edit text is missing or ambiguous, `CURSOR_STALE` when a continued file or directory changed, or an existing preview tunnel when another VM preview is requested |
| `412` | `PRECONDITION_FAILED` because a file changed after the caller read it |
| `413` | A JSON body or bounded file transfer exceeds its route limit |
| `415` | A JSON mutation or binary file upload has the wrong media type |
| `429` | `RATE_LIMITED` because the per-account Sandbox analytics request limit was exceeded, or `WORKSPACE_QUOTA_EXCEEDED` because Sandbox-count or retained workspace-storage capacity is full |
| `502` | The Sandbox service is currently unavailable |
| `503` | The Sandbox runtime, retained-log store, or preview transport is currently unavailable; preview close can also return 503 after disabling the URL when transport cleanup remains pending |

A command that exits non-zero still returns a successful HTTP response. Check `result.exitCode` and `result.timedOut`. Also check `stdoutTruncated` and `stderrTruncated` before assuming output is complete.

The official SDKs raise `BoxComputeError` for API responses and expose its status, stable code,
message, request ID when available, and retryable flag. Network failures raise
`BoxComputeTransportError`. A transport error does not prove whether a mutation reached the service;
use idempotency keys for supported create and operation-start retries.

The public v2 routes do not expose customer APIs for workspace deletion, SDK-specific lifecycle handles, streaming command output, streaming file I/O, a generally available interactive shell or PTY, shared volumes, checkpoints, or forks. VM browser previews expose one HTTP/WebSocket port through a bearer URL for at most one hour; they are not UDP, SSH, permanent hosting, or general ingress, and current SDKs and the CLI do not expose their controls. A separate default-off cooperative connection preview exists only for operator-selected Sandboxes and is not general SSH availability. Generally enabled selected-TCP access opens 1–8 requested ports on an owned active VM to one client for one hour; it is not a public listener or exposed by current SDKs and the CLI. Observable operations provide polling, retained output, and explicit cancellation for one structured command; they are not a general-purpose process or PTY API.

Source: https://boxcompute.ai/docs/limits-and-errors/index.mdx