Documentación de Agent Sandboxes · Referencia
Errores de la API de los sandboxes, y qué hacer
Qué significa cada rechazo de la API y qué hacer después, según su código y su detalle tipado: para las ramas de un programa y el siguiente paso de un agente. Decide según el código y el detalle, nunca según el mensaje, que es una frase para personas y puede cambiar.
Leer un error en cada SDK
Una llamada fallida lanza, rechaza o devuelve un error con un código, el mensaje de la API y, cuando lo tiene, un detalle tipado. Python lanza una subclase de SandboxesError por código (AlreadyExistsError, FailedPreconditionError…) con el detalle en detail; TypeScript rechaza con un SandboxesError cuyo detalle es un campo propio (error.nameTaken); Go devuelve un *sandboxes.Error con un campo por detalle; el Error de Rust tiene code() y details(). Aquí, un nombre ya ocupado reutiliza el sandbox que lo tiene, y un sandbox detenido se reanuda:
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);
Rechazos con un detalle tipado
| Código y detalle | Qué significa | Qué hacer |
|---|---|---|
FAILED_PRECONDITION + Stopped | Una llamada a un sandbox STOPPED, un inicio de sesión SSH o una petición a un puerto, y su ciclo de vida no dice wake_when_stopped. | ResumeSandbox, y repite la llamada. |
UNAVAILABLE + Restoring | Su disco se está trayendo desde almacenamiento de objetos para su inicio; fetched_bytes de total_bytes hasta ahora, a unos 10 s por GiB. | Espera, y repite. |
UNAVAILABLE + NoCapacity | Ningún servidor tiene espacio para él ahora; bound dice qué le faltaba al último, y el fork_count de un fork cuántas copias caben. | Vuelve a intentarlo más tarde, o haz un fork de fork_count copias o menos. |
RESOURCE_EXHAUSTED + LimitReached | Un límite del plan, nombrado por limit con su max: vcpus, largest_size, volume_gib, template_versions, template_gib o secrets. | Elimina o detén lo que lo ocupa, o elige un plan mayor. Los sandboxes en ejecución y en pausa ocupan vCPU. |
RESOURCE_EXHAUSTED + LimitReached, starts_per_minute, _hour, _day | Demasiados inicios en esa ventana móvil: creaciones, copias de forks e inicios de sandboxes detenidos. Los inicios son gratis y limitados. | Repite en retry_time. Si no lo hay, la llamada pide más de lo que permite la ventana: divídela. |
FAILED_PRECONDITION + UsageUnpaid | Ahora nada paga el espacio de trabajo: su uso incluido se agotó y su saldo está vacío. Los sandboxes en ejecución y en pausa se detuvieron. | El propietario agrega saldo, o empieza el plan desde la prueba gratis, en el panel. Se levanta en segundos. |
FAILED_PRECONDITION + AgentSignIn | Un agente de programación no puede llegar a su modelo: variable nombra la variable que hay que vincular, sign_in_command el comando que ejecutar en su lugar. | Vincula un secreto a variable, haz que una persona ejecute sign_in_command en la terminal, o usa OpenCode. |
FAILED_PRECONDITION + WorkspaceChoice | La llamada no nombra ningún espacio de trabajo y el token llega a varios; workspaces los lista. | Envía workspace, su id o su nombre, en la llamada o en el cliente. |
ALREADY_EXISTS + NameTaken | Otro sandbox no eliminado del espacio de trabajo tiene el nombre; sandbox_id es ese sandbox. | Usa ese sandbox, o elige otro nombre. |
Rechazos solo por su código
| Código | Qué significa | Qué hacer |
|---|---|---|
INVALID_ARGUMENT | Un campo está mal, y el mensaje lo nombra y dice qué admite; o un request_id volvió a llegar con otros campos. | Corrige el campo. No reintentes tal cual. |
NOT_FOUND | No existe ese sandbox, plantilla, volumen o secreto, o el token no llega a él. Desde el servidor de un sandbox: el sandbox se movió a otro. | Revisa el id. Los SDK vuelven a conectarse solos cuando un sandbox se movió. |
FAILED_PRECONDITION | El estado no permite la llamada, como dice la llamada: un tamaño nuevo para un sandbox PAUSED, un secreto aún vinculado, un volumen aún montado, una plantilla que aún se está guardando, un escritorio que no se inició. | Haz primero lo que dice el mensaje, y repite. |
ABORTED | Los ajustes del sandbox cambiaron desde que los leíste (if_revision). | Vuelve a leerlo, y rehaz tu cambio. |
RESOURCE_EXHAUSTED | Sin LimitReached: el sandbox ya atiende 64 llamadas a la vez, o un mensaje pasó de su límite (1 MiB por petición, 17 MiB por WriteFiles). | Termina una llamada o espera; mueve un archivo grande con un enlace. |
UNAVAILABLE | Sin detalle: ningún servidor responde ahora, o el sandbox se está moviendo a otro servidor. | Repite en un momento. |
PERMISSION_DENIED | El token de API no tiene acceso al espacio de trabajo, o un token aprobado para el servidor MCP de Agent Sandboxes llamó a otra API. Desde el servidor de un sandbox: un token para otro servidor, tras un traslado. | Dale al token acceso al espacio de trabajo en Ajustes. Los SDK vuelven a conectarse solos tras un traslado. |
UNAUTHENTICATED | El token falta, está mal escrito, caducó o se revocó. Desde el servidor de un sandbox: un token de conexión que caducó o se revocó (revoke_tokens). | Revisa PETHOST_TOKEN. Los SDK piden solos un token de conexión nuevo. |
Una llamada al runtime rechazada con UNAUTHENTICATED, PERMISSION_DENIED o NOT_FOUND por el servidor de un sandbox no hizo nada. Los SDK y la CLI vuelven a llamar a ConnectSandbox una vez y la repiten; un programa propio por HTTP hace lo mismo.
Respuestas que dicen que algo falló
Algunas llamadas tienen éxito y dicen en su respuesta que parte del trabajo falló: la llamada hizo lo que pudo, y la respuesta dice dónde se detuvo.
| Respuesta | Valores | Qué hacer |
|---|---|---|
WriteFilesResponse.failure | NOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUS | Se hicieron done_count cambios; corrige el siguiente y envía el resto. |
ControlDesktopResponse.failure | OFF_SCREEN, UNKNOWN_KEY | Se hicieron done_count acciones; la captura de pantalla muestra la pantalla tras ellas. |
Command.state | TIMED_OUT, STOPPED, LOST | LOST: el sandbox perdió su memoria mientras se ejecutaba; ejecútalo otra vez. |
AgentTurn.state | FAILED, STOPPED, LOST | FAILED: failure_message dice por qué. LOST: vuelve a darle el prompt. |
Sandbox.state_reason | CRASH, UNPAID, IDLE, MAINTENANCE | CRASH: state_message dice por qué; solo ResumeSandbox lo inicia. |
Por MCP, un WriteFiles o un ControlDesktop que se quedó a medias es un error de herramienta, con su JSON tal como lo responde la API.
En un puerto, en un enlace y por SSH
| Respuesta | Qué significa | Qué hacer |
|---|---|---|
| 401 de un puerto | Un puerto privado, y la petición no llevaba Pethost-Token, llevaba uno caducado o el de otro puerto. | Haz público el puerto, o envía un token nuevo de CreateLink. |
| 503 “stopped: resume it” | El sandbox está detenido y no despierta con una petición. SSH dice las mismas palabras. | ResumeSandbox, o activa wake_when_stopped. |
| 503 durante la restauración | Su disco está volviendo desde almacenamiento de objetos. | Espera, y repite. |
| 403 del proxy de salida | Dentro del sandbox: su salida no permite el host o el puerto, y la respuesta dice qué lo rechazó. | Agrega el host a egress.allow. |
| 421 Misdirected Request | Dentro del sandbox: una petición HTTP sin cifrar para otro host distinto de aquel para el que se abrió su conexión. | Nada: el cliente abre una conexión nueva para ese host. |
Reintentar sin riesgo
Una llamada que crea algo toma un request_id: CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand y PromptAgent. Vuelve a enviar el mismo id tras un timeout o una respuesta perdida, y el reintento responde lo que hizo la primera llamada, durante 24 horas. Las demás llamadas que cambian algo son idempotentes tal cual: pausar un sandbox en pausa o eliminar uno eliminado responden con él tal como está. Una salvedad: un sandbox guarda en su disco los ids de sus comandos y turnos, así que uno que perdió su memoria puede haber perdido los de sus últimos segundos, y un reintento de ese comando lo ejecuta otra vez.
Preguntas
¿Qué significa “stopped: resume it”?
El sandbox está detenido y su ciclo de vida no lo despierta con una llamada. ResumeSandbox lo inicia, con sus archivos como los dejó.
¿Por qué se rechaza mi sandbox con LimitReached?
El espacio de trabajo llegó a un límite de su plan, que nombra limit: normalmente vcpus, ocupadas por sandboxes en ejecución y en pausa, o una ventana de inicios, con retry_time.
¿Debo reintentar UNAVAILABLE?
Sí, tras un momento. Con NoCapacity, algo más tarde; con Restoring, cuando el disco haya vuelto.
¿Puedo analizar el mensaje de error?
No: decide según el código y el detalle tipado. El mensaje es una frase para personas y puede cambiar.
Prueba Pethost Agent Sandboxes
Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.