---
title: "Erros da API de sandboxes, e o que fazer | Pethost Agent Sandboxes"
description: "Cada recusa da API de sandboxes, o código e o detalhe tipado dela, o que significa e o que o seu programa ou agente deve fazer em seguida."
---

[Docs do Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/) · Referência

# Erros da API de sandboxes, e o que fazer

Atualizado em 22 de novembro de 2026 · 7 min de leitura

O que cada recusa da API significa e o que fazer em seguida, pelo código e pelo detalhe tipado: para os desvios de um programa e o próximo passo de um agente. Decida pelo código e pelo detalhe, nunca pela mensagem, que é uma frase para pessoas e pode mudar.

## Como ler um erro em cada SDK

Uma chamada que falha lança, rejeita ou devolve um erro com um código, a mensagem da API e, quando há, um detalhe tipado. O Python lança uma subclasse de `SandboxesError` por código (`AlreadyExistsError`, `FailedPreconditionError`…) com o detalhe em `detail`; o TypeScript rejeita com um `SandboxesError` cujo detalhe é um campo próprio (`error.nameTaken`); o Go devolve um `*sandboxes.Error` com um campo por detalhe; o `Error` do Rust tem `code()` e `details()`. Aqui, um nome já em uso reaproveita o sandbox que o tem, e um sandbox parado é retomado:

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);
```

## Recusas com detalhe tipado

| Código e detalhe | O que significa | O que fazer |
| --- | --- | --- |
| `FAILED_PRECONDITION` + `Stopped` | Uma chamada a um sandbox STOPPED, um login SSH ou uma requisição a uma porta, e o ciclo de vida dele não diz `wake_when_stopped`. | `ResumeSandbox`, depois repita a chamada. |
| `UNAVAILABLE` + `Restoring` | O disco está sendo buscado do armazenamento de objetos para o início; `fetched_bytes` de `total_bytes` até agora, cerca de 10 s por GiB. | Espere, depois repita. |
| `UNAVAILABLE` + `NoCapacity` | Nenhum servidor tem espaço para ele agora; `bound` diz o que faltou ao último, e o `fork_count` de um fork, quantas cópias cabem. | Tente de novo mais tarde, ou faça fork de `fork_count` cópias ou menos. |
| `RESOURCE_EXHAUSTED` + `LimitReached` | Um limite do plano, nomeado por `limit` com o seu `max`: `vcpus`, `largest_size`, `volume_gib`, `template_versions`, `template_gib` ou `secrets`. | Exclua ou pare o que o ocupa, ou escolha um plano maior. Sandboxes rodando e pausados ocupam vCPUs. |
| `RESOURCE_EXHAUSTED` + `LimitReached`, `starts_per_minute`, `_hour`, `_day` | Inícios demais nessa janela deslizante: criações, cópias de fork e inícios de sandboxes parados. Inícios são grátis e limitados. | Repita em `retry_time`. Sem ele, a chamada pede mais do que a janela permite: divida-a. |
| `FAILED_PRECONDITION` + `UsageUnpaid` | Nada paga pelo espaço de trabalho agora: o uso incluído acabou e o saldo está vazio. Os sandboxes rodando e pausados foram parados. | O dono adiciona saldo, ou inicia o plano a partir do teste grátis, no painel. A suspensão sai em segundos. |
| `FAILED_PRECONDITION` + `AgentSignIn` | Um agente de código não consegue chegar ao modelo: `variable` nomeia a variável a ligar, `sign_in_command` o comando a rodar em vez disso. | Ligue um segredo a `variable`, peça a uma pessoa que rode `sign_in_command` no terminal, ou use o OpenCode. |
| `FAILED_PRECONDITION` + `WorkspaceChoice` | A chamada não nomeia nenhum espaço de trabalho e o token alcança vários; `workspaces` os lista. | Envie `workspace`, o id ou o nome, na chamada ou no cliente. |
| `ALREADY_EXISTS` + `NameTaken` | Outro sandbox não excluído do espaço de trabalho tem esse nome; `sandbox_id` é esse sandbox. | Use esse sandbox, ou escolha outro nome. |

## Recusas só pelo código

| Código | O que significa | O que fazer |
| --- | --- | --- |
| `INVALID_ARGUMENT` | Um campo está errado, e a mensagem o nomeia e diz o que ele aceita; ou um `request_id` veio de novo com outros campos. | Corrija o campo. Não repita como está. |
| `NOT_FOUND` | Não existe esse sandbox, template, volume ou segredo, ou nenhum que o token alcance. Vindo do servidor de um sandbox: o sandbox mudou para outro. | Confira o id. Os SDKs se conectam de novo sozinhos quando um sandbox muda de servidor. |
| `FAILED_PRECONDITION` | O estado não permite a chamada, como a mensagem diz: um novo tamanho para um sandbox PAUSED, um segredo ainda ligado, um volume ainda montado, um template ainda sendo salvo, um desktop que não iniciou. | Faça antes o que a mensagem diz, depois repita. |
| `ABORTED` | As configurações do sandbox mudaram desde que você as leu (`if_revision`). | Leia de novo e refaça a sua alteração. |
| `RESOURCE_EXHAUSTED` | Sem `LimitReached`: o sandbox já atende 64 chamadas ao mesmo tempo, ou uma mensagem passou do limite (1 MiB por requisição, 17 MiB por `WriteFiles`). | Encerre uma chamada ou espere; mova um arquivo grande por um link. |
| `UNAVAILABLE` | Sem detalhe: nenhum servidor responde agora, ou o sandbox está mudando para outro servidor. | Repita daqui a pouco. |
| `PERMISSION_DENIED` | O token de API não tem acesso ao espaço de trabalho, ou um token aprovado para o servidor MCP do Agent Sandboxes chamou outra API. Vindo do servidor de um sandbox: um token para outro servidor, depois de uma mudança. | Dê ao token acesso ao espaço de trabalho em Configurações. Os SDKs se conectam de novo sozinhos depois de uma mudança. |
| `UNAUTHENTICATED` | O token está ausente, digitado errado, expirado ou revogado. Vindo do servidor de um sandbox: um token de conexão que expirou ou foi revogado (`revoke_tokens`). | Confira o `PETHOST_TOKEN`. Os SDKs pedem um novo token de conexão sozinhos. |

Uma chamada de runtime recusada com `UNAUTHENTICATED`, `PERMISSION_DENIED` ou `NOT_FOUND` pelo servidor de um sandbox não fez nada. Os SDKs e a CLI chamam `ConnectSandbox` de novo uma vez e a repetem; um programa seu por HTTP faz o mesmo.

## Respostas que dizem que algo falhou

Algumas chamadas dão certo e dizem na resposta que parte do trabalho falhou: a chamada fez o que pôde, e a resposta diz onde parou.

| Resposta | Valores | O que fazer |
| --- | --- | --- |
| `WriteFilesResponse.failure` | `NOT_FOUND`, `PERMISSION_DENIED`, `NOT_A_DIRECTORY`, `IS_A_DIRECTORY`, `NO_SPACE`, `EDIT_NOT_FOUND`, `EDIT_AMBIGUOUS` | `done_count` alterações foram feitas; corrija a seguinte e envie o resto. |
| `ControlDesktopResponse.failure` | `OFF_SCREEN`, `UNKNOWN_KEY` | `done_count` ações foram feitas; a captura de tela mostra a tela depois delas. |
| `Command.state` | `TIMED_OUT`, `STOPPED`, `LOST` | `LOST`: o sandbox perdeu a memória enquanto ele rodava; rode de novo. |
| `AgentTurn.state` | `FAILED`, `STOPPED`, `LOST` | `FAILED`: `failure_message` diz por quê. `LOST`: envie o prompt de novo. |
| `Sandbox.state_reason` | `CRASH`, `UNPAID`, `IDLE`, `MAINTENANCE` | `CRASH`: `state_message` diz por quê; só `ResumeSandbox` o inicia. |

Por MCP, um `WriteFiles` ou `ControlDesktop` que parou no meio é um erro de ferramenta, com o JSON como a API o responde.

## Em uma porta, em um link e por SSH

| Resposta | O que significa | O que fazer |
| --- | --- | --- |
| 401 de uma porta | Uma porta privada, e a requisição não tinha `Pethost-Token`, tinha um expirado ou o de outra porta. | Torne a porta pública, ou envie um token novo de `CreateLink`. |
| 503 “stopped: resume it” | O sandbox está parado e não acorda com uma requisição. O SSH diz as mesmas palavras. | `ResumeSandbox`, ou ative `wake_when_stopped`. |
| 503 durante a restauração | O disco está voltando do armazenamento de objetos. | Espere, depois repita. |
| 403 do proxy de saída | Dentro do sandbox: a saída dele não permite o host ou a porta, e a resposta diz o que recusou. | Adicione o host a `egress.allow`. |
| 421 Misdirected Request | Dentro do sandbox: uma requisição HTTP pura para um host diferente daquele para o qual a conexão foi aberta. | Nada: o cliente abre uma nova conexão para esse host. |

## Repetir com segurança

Uma chamada que cria algo recebe um `request_id`: `CreateSandbox`, `ForkSandbox`, `CreateTemplate`, `CreateVolume`, `RunCommand` e `PromptAgent`. Envie o mesmo id de novo depois de um timeout ou de uma resposta perdida, e a nova tentativa responde o que a primeira chamada fez, por 24 horas. As outras chamadas que mudam algo já são idempotentes: pausar um sandbox pausado ou excluir um excluído responde com ele como está. Uma ressalva: um sandbox guarda no disco os ids dos seus comandos e turnos, então um que perdeu a memória pode ter perdido os dos últimos segundos, e uma nova tentativa de um comando desses o roda de novo.

## Perguntas

### O que significa “stopped: resume it”?

O sandbox está parado e o ciclo de vida dele não o acorda com uma chamada. `ResumeSandbox` o inicia, com os arquivos como ele os deixou.

### Por que o meu sandbox é recusado com LimitReached?

O espaço de trabalho chegou a um limite do plano, que `limit` nomeia: em geral `vcpus`, ocupadas por sandboxes rodando e pausados, ou uma janela de inícios, com `retry_time`.

### Devo repetir um UNAVAILABLE?

Sim, depois de um instante. Com `NoCapacity`, um pouco mais tarde; com `Restoring`, quando o disco tiver voltado.

### Posso interpretar a mensagem de erro?

Não: decida pelo código e pelo detalhe tipado. A mensagem é uma frase para pessoas e pode mudar.

[AnteriorLimites do Pethost Agent Sandboxes](https://pethost.dev/pt/docs/sandboxes/limits/)

## Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

[Começar o teste grátis](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/pt/templates/)
- [Sobre nós](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pt/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Termos](https://pethost.dev/terms/)
- [Privacidade](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bancos de dados

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/pt/sandboxes/)
- [Preços](https://pethost.dev/pt/sandboxes/#pricing)
- [Docs](https://pethost.dev/pt/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparativos

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

Alternativas

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