Português
Menu da documentação

Docs do Agent Sandboxes · Referência

Erros da API de sandboxes, e o que fazer

Atualizado em · 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 detalheO que significaO que fazer
FAILED_PRECONDITION + StoppedUma 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 + RestoringO 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 + NoCapacityNenhum 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 + LimitReachedUm 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, _dayIní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 + UsageUnpaidNada 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 + AgentSignInUm 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 + WorkspaceChoiceA 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 + NameTakenOutro 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ódigoO que significaO que fazer
INVALID_ARGUMENTUm 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_FOUNDNã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_PRECONDITIONO 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.
ABORTEDAs configurações do sandbox mudaram desde que você as leu (if_revision).Leia de novo e refaça a sua alteração.
RESOURCE_EXHAUSTEDSem 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.
UNAVAILABLESem detalhe: nenhum servidor responde agora, ou o sandbox está mudando para outro servidor.Repita daqui a pouco.
PERMISSION_DENIEDO 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.
UNAUTHENTICATEDO 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.

RespostaValoresO que fazer
WriteFilesResponse.failureNOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUSdone_count alterações foram feitas; corrija a seguinte e envie o resto.
ControlDesktopResponse.failureOFF_SCREEN, UNKNOWN_KEYdone_count ações foram feitas; a captura de tela mostra a tela depois delas.
Command.stateTIMED_OUT, STOPPED, LOSTLOST: o sandbox perdeu a memória enquanto ele rodava; rode de novo.
AgentTurn.stateFAILED, STOPPED, LOSTFAILED: failure_message diz por quê. LOST: envie o prompt de novo.
Sandbox.state_reasonCRASH, UNPAID, IDLE, MAINTENANCECRASH: 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

RespostaO que significaO que fazer
401 de uma portaUma 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çãoO disco está voltando do armazenamento de objetos.Espere, depois repita.
403 do proxy de saídaDentro 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 RequestDentro 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.

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