---
title: "Errores de la API de los sandboxes, y qué hacer | Pethost Agent Sandboxes"
description: "Cada rechazo de la API de los sandboxes, su código y su detalle tipado, qué significa y qué debe hacer después tu programa o tu agente."
---

[Documentación de Agent Sandboxes](https://pethost.dev/es/docs/sandboxes/) · Referencia

# Errores de la API de los sandboxes, y qué hacer

Actualizado 22 de noviembre de 2026 · 7 min de lectura

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:

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

## 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.

[AnteriorLímites de Pethost Agent Sandboxes](https://pethost.dev/es/docs/sandboxes/limits/)

## 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.

[Empezar la prueba gratis](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Plantillas](https://pethost.dev/es/templates/)
- [Sobre nosotros](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/es/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Términos](https://pethost.dev/terms/)
- [Privacidad](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de datos

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

Agent Sandboxes

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

Comparativas

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

Alternativas

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