---
title: "Fehler der Sandboxes-API, und was zu tun ist | Pethost Agent Sandboxes"
description: "Jede Ablehnung der Sandboxes-API, ihr Code und ihr typisiertes Detail, was sie bedeutet und was dein Programm oder dein Agent als Nächstes tun sollte."
---

[Doku zu Agent Sandboxes](https://pethost.dev/de/docs/sandboxes/) · Referenz

# Fehler der Sandboxes-API, und was zu tun ist

Aktualisiert 22. November 2026 · 7 Min. Lesezeit

Was jede Ablehnung der API bedeutet und was als Nächstes zu tun ist, nach ihrem Code und ihrem typisierten Detail: für die Verzweigungen eines Programms und den nächsten Schritt eines Agenten. Verzweige nach dem Code und dem Detail, nie nach der Nachricht, die ein Satz für Menschen ist und sich ändern kann.

## Einen Fehler in jedem SDK lesen

Ein gescheiterter Aufruf wirft, lehnt ab oder gibt einen Fehler zurück, mit einem Code, der Nachricht der API und, wo es eins gibt, einem typisierten Detail. Python wirft pro Code eine Unterklasse von `SandboxesError` (`AlreadyExistsError`, `FailedPreconditionError`…) mit dem Detail in `detail`; TypeScript lehnt mit einem `SandboxesError` ab, dessen Detail ein eigenes Feld ist (`error.nameTaken`); Go gibt einen `*sandboxes.Error` mit einem Feld pro Detail zurück; der `Error` von Rust hat `code()` und `details()`. Hier nimmt ein schon vergebener Name die Sandbox, die ihn hat, und eine gestoppte Sandbox wird fortgesetzt:

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

## Ablehnungen mit typisiertem Detail

| Code und Detail | Was es bedeutet | Was zu tun ist |
| --- | --- | --- |
| `FAILED_PRECONDITION` + `Stopped` | Ein Aufruf in eine STOPPED-Sandbox, ein SSH-Login oder ein Port-Request, und ihr Lebenszyklus sagt nicht `wake_when_stopped`. | `ResumeSandbox`, dann den Aufruf wiederholen. |
| `UNAVAILABLE` + `Restoring` | Die Disk wird für den Start aus dem Objektspeicher geholt; bisher `fetched_bytes` von `total_bytes`, etwa 10 s pro GiB. | Warten, dann wiederholen. |
| `UNAVAILABLE` + `NoCapacity` | Kein Server hat gerade Platz dafür; `bound` sagt, was dem letzten fehlte, und bei einem Fork `fork_count`, wie viele Kopien passen. | Später noch einmal versuchen, oder `fork_count` Kopien oder weniger forken. |
| `RESOURCE_EXHAUSTED` + `LimitReached` | Ein Limit des Tarifs, genannt von `limit` mit seinem `max`: `vcpus`, `largest_size`, `volume_gib`, `template_versions`, `template_gib` oder `secrets`. | Lösch oder stopp, was es belegt, oder wähl einen größeren Tarif. Laufende und pausierte Sandboxes belegen vCPUs. |
| `RESOURCE_EXHAUSTED` + `LimitReached`, `starts_per_minute`, `_hour`, `_day` | Zu viele Starts in diesem gleitenden Zeitfenster: Erstellungen, Kopien von Forks und Starts gestoppter Sandboxes. Starts sind kostenlos und begrenzt. | Zur `retry_time` wiederholen. Ohne eine verlangt der Aufruf mehr, als das Zeitfenster erlaubt: Teil ihn auf. |
| `FAILED_PRECONDITION` + `UsageUnpaid` | Gerade bezahlt nichts den Workspace: Sein enthaltener Verbrauch ist aufgebraucht und sein Guthaben leer. Laufende und pausierte Sandboxes wurden gestoppt. | Wer den Workspace besitzt, lädt das Guthaben auf oder startet den Tarif aus der Testphase heraus, in der Konsole. Die Sperre fällt in Sekunden. |
| `FAILED_PRECONDITION` + `AgentSignIn` | Ein Coding-Agent erreicht sein Modell nicht: `variable` nennt die zu bindende Variable, `sign_in_command` den Befehl, der stattdessen auszuführen ist. | Binde ein Secret an `variable`, lass eine Person `sign_in_command` im Terminal ausführen, oder nimm OpenCode. |
| `FAILED_PRECONDITION` + `WorkspaceChoice` | Der Aufruf nennt keinen Workspace, und das Token erreicht mehrere; `workspaces` listet sie. | Schick `workspace`, seine ID oder seinen Namen, im Aufruf oder im Client. |
| `ALREADY_EXISTS` + `NameTaken` | Eine andere, nicht gelöschte Sandbox des Workspace hat den Namen; `sandbox_id` ist diese Sandbox. | Nimm diese Sandbox, oder wähl einen anderen Namen. |

## Ablehnungen nur mit Code

| Code | Was es bedeutet | Was zu tun ist |
| --- | --- | --- |
| `INVALID_ARGUMENT` | Ein Feld ist falsch, und die Nachricht nennt es und sagt, was es nimmt; oder eine `request_id` kam erneut mit anderen Feldern. | Korrigier das Feld. Nicht unverändert wiederholen. |
| `NOT_FOUND` | Keine solche Sandbox, Vorlage, kein solches Volume oder Secret, oder keins, das das Token erreicht. Vom Server einer Sandbox: Die Sandbox ist auf einen anderen umgezogen. | Prüf die ID. Die SDKs verbinden sich selbst neu, wenn eine Sandbox umgezogen ist. |
| `FAILED_PRECONDITION` | Der Zustand erlaubt den Aufruf nicht, wie der Aufruf sagt: eine neue Größe für eine PAUSED-Sandbox, ein noch gebundenes Secret, ein noch gemountetes Volume, eine Vorlage, die noch gespeichert wird, ein Desktop, der nicht gestartet ist. | Tu zuerst, was die Nachricht sagt, dann wiederhole. |
| `ABORTED` | Die Einstellungen der Sandbox haben sich geändert, seit du sie gelesen hast (`if_revision`). | Lies sie neu und mach deine Änderung noch einmal. |
| `RESOURCE_EXHAUSTED` | Ohne `LimitReached`: Die Sandbox bedient schon 64 Aufrufe gleichzeitig, oder eine Nachricht lag über ihrer Grenze (1 MiB pro Request, 17 MiB pro `WriteFiles`). | Beende einen Aufruf oder warte; bewege eine große Datei über einen Link. |
| `UNAVAILABLE` | Ohne Detail: Gerade antwortet kein Server, oder die Sandbox zieht auf einen anderen Server um. | Gleich wiederholen. |
| `PERMISSION_DENIED` | Das API-Token hat keinen Zugriff auf den Workspace, oder ein Token, das für den MCP-Server von Agent Sandboxes bestätigt wurde, hat eine andere API aufgerufen. Vom Server einer Sandbox: ein Token für einen anderen Server, nach einem Umzug. | Gib dem Token in den Einstellungen Zugriff auf den Workspace. Die SDKs verbinden sich nach einem Umzug selbst neu. |
| `UNAUTHENTICATED` | Das Token fehlt, ist vertippt, abgelaufen oder gelöscht. Vom Server einer Sandbox: ein Verbindungs-Token, das abgelaufen ist oder widerrufen wurde (`revoke_tokens`). | Prüf `PETHOST_TOKEN`. Die SDKs holen selbst ein neues Verbindungs-Token. |

Ein Runtime-Aufruf, den der Server einer Sandbox mit `UNAUTHENTICATED`, `PERMISSION_DENIED` oder `NOT_FOUND` abgelehnt hat, hat nichts getan. Die SDKs und die CLI fragen `ConnectSandbox` einmal neu und wiederholen ihn; ein eigenes Programm über HTTP tut dasselbe.

## Antworten, die sagen, dass etwas scheiterte

Manche Aufrufe gelingen und sagen in ihrer Antwort, dass ein Teil der Arbeit scheiterte: Der Aufruf hat getan, was er konnte, und die Antwort sagt, wo er aufgehört hat.

| Antwort | Werte | Was zu tun ist |
| --- | --- | --- |
| `WriteFilesResponse.failure` | `NOT_FOUND`, `PERMISSION_DENIED`, `NOT_A_DIRECTORY`, `IS_A_DIRECTORY`, `NO_SPACE`, `EDIT_NOT_FOUND`, `EDIT_AMBIGUOUS` | `done_count` Änderungen wurden gemacht; korrigier die nächste und schick den Rest. |
| `ControlDesktopResponse.failure` | `OFF_SCREEN`, `UNKNOWN_KEY` | `done_count` Aktionen wurden erledigt; der Screenshot zeigt den Bildschirm danach. |
| `Command.state` | `TIMED_OUT`, `STOPPED`, `LOST` | `LOST`: Die Sandbox hat ihren RAM verloren, während er lief; führ ihn noch einmal aus. |
| `AgentTurn.state` | `FAILED`, `STOPPED`, `LOST` | `FAILED`: `failure_message` sagt, warum. `LOST`: erneut einen Prompt geben. |
| `Sandbox.state_reason` | `CRASH`, `UNPAID`, `IDLE`, `MAINTENANCE` | `CRASH`: `state_message` sagt, warum; nur `ResumeSandbox` startet sie. |

Über MCP ist ein `WriteFiles` oder `ControlDesktop`, das vorzeitig aufgehört hat, ein Tool-Fehler, sein JSON so, wie die API antwortet.

## An einem Port, an einem Link und über SSH

| Antwort | Was es bedeutet | Was zu tun ist |
| --- | --- | --- |
| 401 von einem Port | Ein privater Port, und der Request hatte kein `Pethost-Token`, ein abgelaufenes oder das eines anderen Ports. | Mach den Port öffentlich, oder schick ein frisches Token von `CreateLink`. |
| 503 „stopped: resume it“ | Die Sandbox ist gestoppt und wacht durch einen Request nicht auf. SSH sagt dieselben Worte. | `ResumeSandbox`, oder schalt `wake_when_stopped` ein. |
| 503 beim Wiederherstellen | Die Disk kommt aus dem Objektspeicher zurück. | Warten, dann wiederholen. |
| 403 vom Egress-Proxy | In der Sandbox: Der Egress erlaubt den Host oder Port nicht, und die Antwort sagt, was abgelehnt hat. | Füg den Host zu `egress.allow` hinzu. |
| 421 Misdirected Request | In der Sandbox: ein einfacher HTTP-Request für einen anderen Host als den, zu dem seine Verbindung geöffnet wurde. | Nichts: Der Client öffnet eine neue Verbindung für diesen Host. |

## Sicher wiederholen

Ein Aufruf, der etwas erstellt, nimmt eine `request_id`: `CreateSandbox`, `ForkSandbox`, `CreateTemplate`, `CreateVolume`, `RunCommand` und `PromptAgent`. Schick nach einem Timeout oder einer verlorenen Antwort dieselbe ID noch einmal, und die Wiederholung antwortet 24 Stunden lang mit dem, was der erste Aufruf getan hat. Die anderen Aufrufe, die etwas ändern, sind von sich aus idempotent: Eine Pause einer pausierten Sandbox, ein Löschen einer gelöschten antworten mit ihr, wie sie ist. Eine Einschränkung: Eine Sandbox hält die IDs ihrer Befehle und Turns auf ihrer Disk, also hat eine, die ihren RAM verloren hat, die ihrer letzten Sekunden vielleicht verloren, und eine Wiederholung eines solchen Befehls führt ihn noch einmal aus.

## Fragen

### Was bedeutet „stopped: resume it“?

Die Sandbox ist gestoppt, und ihr Lebenszyklus weckt sie bei einem Aufruf nicht. `ResumeSandbox` startet sie, ihre Dateien, wie sie sie verlassen hat.

### Warum wird meine Sandbox mit LimitReached abgelehnt?

Der Workspace hat ein Limit seines Tarifs erreicht, das `limit` nennt: meist `vcpus`, belegt von laufenden und pausierten Sandboxes, oder ein Zeitfenster für Starts, mit `retry_time`.

### Soll ich UNAVAILABLE wiederholen?

Ja, nach einem Moment. Mit `NoCapacity` etwas später; mit `Restoring`, sobald die Disk zurück ist.

### Kann ich die Fehlermeldung parsen?

Nein: Verzweige nach dem Code und dem typisierten Detail. Die Nachricht ist ein Satz für Menschen und kann sich ändern.

[ZurückLimits von Pethost Agent Sandboxes](https://pethost.dev/de/docs/sandboxes/limits/)

## Pethost Agent Sandboxes ausprobieren

Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.

[Testphase starten](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Vorlagen](https://pethost.dev/de/templates/)
- [Über uns](https://pethost.dev/about/)
- [Doku](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/de/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [AGB](https://pethost.dev/terms/)
- [Datenschutz](https://pethost.dev/privacy/)
- [Erstattung](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Datenbanken

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/de/sandboxes/)
- [Preise](https://pethost.dev/de/sandboxes/#pricing)
- [Doku](https://pethost.dev/de/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Vergleiche

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

Alternativen

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