Docs do Agent Sandboxes · Referência
Erros da API de sandboxes, e o que fazer
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:
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")
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);
});
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)
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.
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.