Check Your Limits

A limit comes from one of four places, and the place decides who can change it. A limit can refuse a request or truncate output. If a request fails, read its retry field and check its outcome before retrying; a refusal does not remove an existing sandbox. See Recover from Errors.

Source	Who Sets It	Where to Read It
BoxRouter request rules	Fixed for everyone	The table below
Your route	The provider and class you landed on	The sandbox’s `limits` and `lifetime`
Your workspace	Capacity allocated to your workspace	The `429` message
Your provider account	Your plan at the provider	The provider’s dashboard

Fixed Request Limits

Limit	Value	When Exceeded	Recovery
JSON request body	1 MiB	`413 invalid_request`	Send a smaller body. Store larger files in a Volume.
Labels on a sandbox	64 labels; keys up to 63 characters; values up to 255	`400 invalid_request`	Send fewer or shorter labels.
`Idempotency-Key` header	1 to 128 characters	`400 invalid_request`	Send a UUID. Some calls require it; save it before sending to reconcile an uncertain response.
Copies in one run	100	`429 run_limit_exceeded`	Ask for 100 or fewer, or split the work. See run copies.
Entries in one directory listing	10,000	`413 resource_limit`	List part of the directory from a command, such as `ls \| head -n 1000`.

BoxRouter reads and discards up to 64 MiB of an oversized body so your client can finish sending and read the 413.

Volume Limits

Limit	Value	When Exceeded	Recovery
Storage per workspace	10 GiB	`413 resource_limit` on a `write` or `branch` attach, a save, or an upload	Delete files or volumes you no longer need.
Volumes per workspace	20	`413 resource_limit` on create	Delete a volume before creating another.
Checkpoints per volume	10	None; a save over the limit removes the oldest automatic (pause or destroy) checkpoint first, then the oldest saved one; the head is kept	Read `limits.max_checkpoints` on the volume.
One uploaded file	256 GiB, within the storage left	`413 resource_limit`	Split the file. With 10 GiB of storage, the storage limit applies first.

See Volumes for how each limit behaves.

Limits Your Route Sets

Each sandbox reports the limits of the route it runs on. Read limits and lifetime.max_seconds before you size work. Enter the sandbox ID when prompted:

import json
from boxrouter import BoxRouter

sandbox_id = input("Sandbox ID: ")

with BoxRouter() as client:
    box = client.sandboxes.get(sandbox_id)
    print(json.dumps({
        "limits": box.limits.to_dict(),
        "max_seconds": box.lifetime.max_seconds,
    }, indent=2))

import { createInterface } from 'node:readline/promises';
import { BoxRouter } from '@boxrouter/sdk';

const rl = createInterface({ input: process.stdin, output: process.stdout });
const sandboxId = await rl.question('Sandbox ID: ');
rl.close();

const client = new BoxRouter();
try {
  const box = await client.sandboxes.get(sandboxId);
  console.log(JSON.stringify({
    limits: box.limits,
    max_seconds: box.lifetime.max_seconds,
  }, null, 2));
} finally {
  await client.close();
}

(
  set -euo pipefail
  printf 'Sandbox ID: '
  read -r SANDBOX_ID
  boxrouter get "$SANDBOX_ID" | jq '{limits, max_seconds: .lifetime.max_seconds}'
)

Field	Limits	When Exceeded
`file_transfer_bytes`	A file `read` or `write`, and a listing as JSON.	`413 output_limit` for a read or listing, `413 resource_limit` for a write. Use a Volume for larger files.
`buffered_output_bytes`	Combined stdout and stderr of one buffered command.	Output can be cut, or delivery can fail after the command runs. See commands.
`lifetime.max_seconds`	The longest lifetime this route grants.	The route is excluded from the request.

For files larger than file_transfer_bytes, use Volumes. Launch preparation and terminal time are in launch limits. A runner’s job time is in Actions runners.

Limits Your Workspace Shares

Every API key in a workspace draws on the same allowance, so a busy loop on one key can push the others into 429 rate_limited. Two limits apply:

Rate. By default, 32 requests per second.
Requests in progress. How many of your requests BoxRouter works on at once. One workspace can use at most a quarter of a server’s capacity, so no single workspace fills a server.

A command that waits on its provider keeps its place until it finishes, so slow commands use up your share faster than quick ones. The count depends on the server’s size. Past either limit, the call fails with 429 rate_limited and the message names the number that applied. The request did nothing, and the error says retry: safe: the SDKs and CLI wait retry_after_seconds and resend it with the same idempotency key, up to their max_retries. Over plain HTTP, you wait and resend it. Send fewer requests at once. If your steady load needs more, contact support.

Limits Your Provider Account Sets

Your provider can enforce plan limits on the account you connected, such as concurrent sandboxes, storage, or the longest lifetime. BoxRouter may learn a limit when the provider refuses a request. Check fix and any native_code or native_message the error includes. A quota refusal returns 429 provider_quota, for example with native_code: QUOTA_EXCEEDED, but the code and status depend on the provider and operation. Its retry is after_fix: free capacity or raise the limit in the provider account. If outcome is unknown, retry is check_outcome: check whether work started before retrying or choosing another route. When the image store is full, BoxRouter frees space only by deleting the image copies it created and recorded. Delete images or templates you no longer need in your provider account.

Next Steps

Recover from Errors

Recover after a refused or failed call.

Capabilities and Isolation

Transfer sizes per provider.

Set Workspace Routing

Choose providers and what pays first.

Get Started

Sandboxes

Routing and Providers

Errors and Limits

Cost and Billing

Security and Privacy

Clients