---
title: "Errors of the sandboxes API, and what to do | Pethost Agent Sandboxes"
description: "Every refusal of the sandboxes API, its code and typed detail, what it means and what your program or agent should do next."
---

[Agent Sandboxes docs](https://pethost.dev/docs/sandboxes/) · Reference

# Errors of the sandboxes API, and what to do

Updated 22 November 2026 · 7 min read

What each refusal of the API means and what to do next, by its code and its typed detail: for a program's branches and an agent's next step. Branch on the code and the detail, never on the message, which is a sentence for people and may change.

## Reading an error in each SDK

A failed call raises, rejects or returns an error with a code, the API's message and, where it has one, a typed detail. Python raises a subclass of `SandboxesError` per code (`AlreadyExistsError`, `FailedPreconditionError`…) with the detail in `detail`; TypeScript rejects with a `SandboxesError` whose detail is a field of its own (`error.nameTaken`); Go returns a `*sandboxes.Error` with a field per detail; Rust's `Error` has `code()` and `details()`. Here a name already taken reuses the sandbox that has it, and a stopped sandbox is resumed:

Python

```
from pethost.sandboxes import AlreadyExistsError, FailedPreconditionError, NameTaken, Stopped

try:
    sandbox = sandboxes.create_sandbox("base", name="api-dev")
except AlreadyExistsError as error:
    if not isinstance(error.detail, NameTaken):
        raise
    sandbox = sandboxes.get_sandbox(error.detail.sandbox_id)  # the sandbox that has the name

try:
    command = sandboxes.run_command(sandbox.sandbox_id, command="make test")
except FailedPreconditionError as error:
    if not isinstance(error.detail, Stopped):
        raise
    sandboxes.resume_sandbox(sandbox.sandbox_id)
    command = sandboxes.run_command(sandbox.sandbox_id, command="make test")
```

TypeScript

```
const created = await sandboxes.createSandbox({ template: "base", name: "api-dev" }).catch(async (error) => {
  if (!(error instanceof SandboxesError) || !error.nameTaken) throw error;
  return sandboxes.getSandbox({ sandboxId: error.nameTaken.sandboxId }); // the sandbox that has the name
});

const test = { sandboxId: created.sandboxId, command: "make test" };
const command = await sandboxes.runCommand(test).catch(async (error) => {
  if (!(error instanceof SandboxesError) || !error.stopped) throw error;
  await sandboxes.resumeSandbox({ sandboxId: created.sandboxId });
  return sandboxes.runCommand(test);
});
```

Go

```
created, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base", Name: "api-dev"})
if e, ok := errors.AsType[*sandboxes.Error](err); ok && e.NameTaken != nil {
	created, err = client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: e.NameTaken.SandboxID})
}
if err != nil {
	log.Fatal(err)
}

test := &sandboxes.RunCommandRequest{SandboxID: created.SandboxID, Command: "make test"}
command, err := client.RunCommand(ctx, test)
if e, ok := errors.AsType[*sandboxes.Error](err); ok && e.Stopped != nil {
	if _, err = client.ResumeSandbox(ctx, &sandboxes.ResumeSandboxRequest{SandboxID: created.SandboxID}); err == nil {
		command, err = client.RunCommand(ctx, test)
	}
}
if err != nil {
	log.Fatal(err)
}
fmt.Println(command.State)
```

Rust

```
use pethost::sandboxes::ErrorDetail;

let request = CreateSandboxRequest { template: "base".into(), name: "api-dev".into(), ..Default::default() };
let created = match sandboxes.create_sandbox(request).await {
    Ok(sandbox) => sandbox,
    Err(error) => match error.details().iter().find_map(|detail| match detail {
        ErrorDetail::NameTaken(taken) => Some(taken.sandbox_id.clone()),
        _ => None,
    }) {
        Some(sandbox_id) => sandboxes.get_sandbox(GetSandboxRequest { sandbox_id, ..Default::default() }).await?,
        None => return Err(error.into()),
    },
};

let test = RunCommandRequest { sandbox_id: created.sandbox_id.clone(), command: "make test".into(), ..Default::default() };
let command = match sandboxes.run_command(test.clone()).await {
    Err(error) if error.details().iter().any(|detail| matches!(detail, ErrorDetail::Stopped(_))) => {
        let resume = ResumeSandboxRequest { sandbox_id: created.sandbox_id.clone(), ..Default::default() };
        sandboxes.resume_sandbox(resume).await?;
        sandboxes.run_command(test).await?
    }
    other => other?,
};
println!("{:?}", command.state);
```

## Refusals with a typed detail

| Code and detail | What it means | What to do |
| --- | --- | --- |
| `FAILED_PRECONDITION` + `Stopped` | A call into a STOPPED sandbox, an SSH login or a port request, and its lifecycle does not say `wake_when_stopped`. | `ResumeSandbox`, then repeat the call. |
| `UNAVAILABLE` + `Restoring` | Its disk is being fetched from object storage for its start; `fetched_bytes` of `total_bytes` so far, about 10 s a GiB. | Wait, then repeat. |
| `UNAVAILABLE` + `NoCapacity` | No server has room for it now; `bound` says what the last one lacked, and a fork's `fork_count` how many copies fit. | Try again later, or fork `fork_count` copies or fewer. |
| `RESOURCE_EXHAUSTED` + `LimitReached` | A limit of the plan, named by `limit` with its `max`: `vcpus`, `largest_size`, `volume_gib`, `template_versions`, `template_gib`, or `secrets`. | Delete or stop what holds it, or choose a larger plan. Running and paused sandboxes hold vCPUs. |
| `RESOURCE_EXHAUSTED` + `LimitReached`, `starts_per_minute`, `_hour`, `_day` | Too many starts in that sliding window: creates, fork copies and starts of stopped sandboxes. Starts are free and bounded. | Repeat at `retry_time`. Without one, the call asks more than the window allows: split it. |
| `FAILED_PRECONDITION` + `UsageUnpaid` | Nothing pays for the workspace now: its included usage is used up and its balance is empty. Running and paused sandboxes were stopped. | The owner adds to the balance, or starts the plan from the trial, in the console. It lifts within seconds. |
| `FAILED_PRECONDITION` + `AgentSignIn` | A coding agent cannot reach its model: `variable` names the variable to bind, `sign_in_command` the command to run instead. | Bind a secret to `variable`, have a person run `sign_in_command` in the terminal, or use OpenCode. |
| `FAILED_PRECONDITION` + `WorkspaceChoice` | The call names no workspace and the token reaches several; `workspaces` lists them. | Send `workspace`, its id or name, in the call or the client. |
| `ALREADY_EXISTS` + `NameTaken` | Another sandbox of the workspace that is not deleted has the name; `sandbox_id` is that sandbox. | Use that sandbox, or choose another name. |

## Refusals by their code alone

| Code | What it means | What to do |
| --- | --- | --- |
| `INVALID_ARGUMENT` | A field is wrong, and the message names it and says what it takes; or a `request_id` came again with other fields. | Fix the field. Do not retry as is. |
| `NOT_FOUND` | No such sandbox, template, volume or secret, or none the token reaches. From a sandbox's server: the sandbox moved to another. | Check the id. The SDKs connect again by themselves when a sandbox moved. |
| `FAILED_PRECONDITION` | The state does not allow the call, as the call says: a new size for a PAUSED sandbox, a secret still bound, a volume still mounted, a template still saving, a desktop that did not start. | Do what the message says first, then repeat. |
| `ABORTED` | The sandbox's settings changed since you read them (`if_revision`). | Read it again, and redo your change. |
| `RESOURCE_EXHAUSTED` | Without `LimitReached`: the sandbox serves 64 calls at once already, or a message was over its bound (1 MiB a request, 17 MiB a `WriteFiles`). | End a call or wait; move a large file through a link. |
| `UNAVAILABLE` | Without a detail: no server answers now, or the sandbox is moving to another server. | Repeat in a moment. |
| `PERMISSION_DENIED` | The API token is not granted the workspace, or a token approved for Agent Sandboxes' MCP server called another API. From a sandbox's server: a token for another server, after a move. | Grant the token the workspace in Settings. The SDKs connect again by themselves after a move. |
| `UNAUTHENTICATED` | The token is missing, mistyped, expired or revoked. From a sandbox's server: a connection token that expired or was revoked (`revoke_tokens`). | Check `PETHOST_TOKEN`. The SDKs ask for a new connection token by themselves. |

A runtime call refused with `UNAUTHENTICATED`, `PERMISSION_DENIED` or `NOT_FOUND` by a sandbox's server did nothing. The SDKs and the CLI ask `ConnectSandbox` again once and repeat it; a program of your own over HTTP does the same.

## Answers that say something failed

Some calls succeed and say in their answer that part of the work failed: the call did what it could, and the answer says where it stopped.

| Answer | Values | What to do |
| --- | --- | --- |
| `WriteFilesResponse.failure` | `NOT_FOUND`, `PERMISSION_DENIED`, `NOT_A_DIRECTORY`, `IS_A_DIRECTORY`, `NO_SPACE`, `EDIT_NOT_FOUND`, `EDIT_AMBIGUOUS` | `done_count` changes were made; fix the next one and send the rest. |
| `ControlDesktopResponse.failure` | `OFF_SCREEN`, `UNKNOWN_KEY` | `done_count` actions were done; the screenshot shows the screen after them. |
| `Command.state` | `TIMED_OUT`, `STOPPED`, `LOST` | `LOST`: the sandbox lost its memory while it ran; run it again. |
| `AgentTurn.state` | `FAILED`, `STOPPED`, `LOST` | `FAILED`: `failure_message` says why. `LOST`: prompt again. |
| `Sandbox.state_reason` | `CRASH`, `UNPAID`, `IDLE`, `MAINTENANCE` | `CRASH`: `state_message` says why; only `ResumeSandbox` starts it. |

Over MCP, a `WriteFiles` or `ControlDesktop` that stopped short is a tool error, its JSON as the API answers it.

## At a port, at a link and over SSH

| Answer | What it means | What to do |
| --- | --- | --- |
| 401 from a port | A private port, and the request had no `Pethost-Token`, an expired one or another port's. | Make the port public, or send a fresh token from `CreateLink`. |
| 503 “stopped: resume it” | The sandbox is stopped and does not wake by a request. SSH says the same words. | `ResumeSandbox`, or turn on `wake_when_stopped`. |
| 503 while restoring | Its disk is coming back from object storage. | Wait, then repeat. |
| 403 from the egress proxy | Inside the sandbox: its egress does not allow the host or port, and the answer says what refused it. | Add the host to `egress.allow`. |
| 421 Misdirected Request | Inside the sandbox: a plain HTTP request for another host than its connection was opened to. | Nothing: the client opens a new connection for that host. |

## Retrying safely

A call that makes something takes a `request_id`: `CreateSandbox`, `ForkSandbox`, `CreateTemplate`, `CreateVolume`, `RunCommand` and `PromptAgent`. Send the same id again after a timeout or a lost answer, and the retry answers what the first call did, for 24 hours. The other calls that change something are idempotent as they are: a pause of a paused sandbox, a delete of a deleted one, answer it as it is. One caveat: a sandbox keeps the ids of its commands and turns on its disk, so one that lost its memory may have lost those of its last seconds, and a retry of such a command runs it again.

## Questions

### What does “stopped: resume it” mean?

The sandbox is stopped and its lifecycle does not wake it at a call. `ResumeSandbox` starts it, its files as it left them.

### Why is my sandbox refused with LimitReached?

The workspace reached a limit of its plan, which `limit` names: usually `vcpus`, held by running and paused sandboxes, or a starts window, with `retry_time`.

### Should I retry UNAVAILABLE?

Yes, after a moment. With `NoCapacity`, a little later; with `Restoring`, once the disk is back.

### Can I parse the error message?

No: branch on the code and the typed detail. The message is a sentence for people and may change.

[PreviousLimits of Pethost Agent Sandboxes](https://pethost.dev/docs/sandboxes/limits/)

## Try Pethost Agent Sandboxes

A 7-day trial with $1 of usage and 4 vCPUs, with a card. Then a plan from $20 a month, which includes as much usage.

[Start the trial](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/templates/)
- [About](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Terms](https://pethost.dev/terms/)
- [Privacy](https://pethost.dev/privacy/)
- [Refunds](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Databases

- [Postgres](https://pethost.dev/postgres/)
- [Valkey](https://pethost.dev/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/sandboxes/)
- [Pricing](https://pethost.dev/sandboxes/#pricing)
- [Docs](https://pethost.dev/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparisons

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/blog/coolify-cloud-vs-dokploy-cloud/)
- [Railway vs Render vs Fly.io pricing](https://pethost.dev/blog/railway-vs-render-vs-fly-io-pricing/)
- [Managed Docker Compose hosting](https://pethost.dev/blog/managed-docker-compose-hosting/)

Alternatives

- [Railway alternatives](https://pethost.dev/blog/railway-alternatives/)
- [Heroku alternatives](https://pethost.dev/blog/heroku-alternatives/)
- [Dokploy alternatives](https://pethost.dev/blog/dokploy-alternatives/)
- [Coolify alternatives](https://pethost.dev/blog/coolify-alternatives/)
- [Render alternatives](https://pethost.dev/blog/render-alternatives/)
- [Sliplane alternatives](https://pethost.dev/blog/sliplane-alternatives/)
