---
title: "Błędy API sandboxów i co z nimi zrobić | Pethost Agent Sandboxes"
description: "Każda odmowa API sandboxów, jej kod i typowany szczegół, co oznacza i co twój program albo agent powinien zrobić dalej."
---

[Dokumentacja Agent Sandboxes](https://pethost.dev/pl/docs/sandboxes/) · Referencja

# Błędy API sandboxów i co z nimi zrobić

Zaktualizowano 22 listopada 2026 · 6 min czytania

Co oznacza każda odmowa API i co zrobić dalej, według jej kodu i typowanego szczegółu: dla gałęzi w programie i następnego kroku agenta. Rozgałęziaj po kodzie i szczególe, nigdy po komunikacie, który jest zdaniem dla ludzi i może się zmienić.

## Odczytywanie błędu w każdym SDK

Nieudane wywołanie rzuca wyjątek, odrzuca obietnicę albo zwraca błąd z kodem, komunikatem API i, jeśli jest, typowanym szczegółem. Python rzuca podklasę `SandboxesError` dla każdego kodu (`AlreadyExistsError`, `FailedPreconditionError`…) ze szczegółem w `detail`; TypeScript odrzuca z `SandboxesError`, którego szczegół jest osobnym polem (`error.nameTaken`); Go zwraca `*sandboxes.Error` z polem na każdy szczegół; `Error` w Rust ma `code()` i `details()`. Tutaj zajęta nazwa oznacza ponowne użycie sandboxa, który ją ma, a zatrzymany sandbox zostaje wznowiony:

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

## Odmowy z typowanym szczegółem

| Kod i szczegół | Co oznacza | Co zrobić |
| --- | --- | --- |
| `FAILED_PRECONDITION` + `Stopped` | Wywołanie do sandboxa STOPPED, logowanie SSH albo żądanie do portu, a jego cykl życia nie ma `wake_when_stopped`. | `ResumeSandbox`, a potem powtórz wywołanie. |
| `UNAVAILABLE` + `Restoring` | Jego dysk jest pobierany z magazynu obiektów na potrzeby startu; dotąd `fetched_bytes` z `total_bytes`, ok. 10 s na GiB. | Poczekaj, a potem powtórz. |
| `UNAVAILABLE` + `NoCapacity` | Żaden serwer nie ma teraz dla niego miejsca; `bound` mówi, czego zabrakło ostatniemu, a `fork_count` przy forku, ile kopii się zmieści. | Spróbuj później albo zrób fork na `fork_count` kopii lub mniej. |
| `RESOURCE_EXHAUSTED` + `LimitReached` | Limit planu, nazwany przez `limit` razem z `max`: `vcpus`, `largest_size`, `volume_gib`, `template_versions`, `template_gib` albo `secrets`. | Usuń albo zatrzymaj to, co go zajmuje, albo wybierz większy plan. vCPU zajmują działające i wstrzymane sandboxy. |
| `RESOURCE_EXHAUSTED` + `LimitReached`, `starts_per_minute`, `_hour`, `_day` | Za dużo startów w tym przesuwnym oknie: utworzeń, kopii z forków i startów zatrzymanych sandboxów. Starty są darmowe i ograniczone. | Powtórz o `retry_time`. Bez niego wywołanie prosi o więcej, niż pozwala okno: podziel je. |
| `FAILED_PRECONDITION` + `UsageUnpaid` | Nic teraz nie płaci za przestrzeń roboczą: zużycie w planie się skończyło, a saldo jest puste. Działające i wstrzymane sandboxy zostały zatrzymane. | Właściciel doładowuje saldo albo zaczyna plan zamiast okresu próbnego, w panelu. Blokada znika w ciągu kilku sekund. |
| `FAILED_PRECONDITION` + `AgentSignIn` | Agent kodujący nie może dotrzeć do swojego modelu: `variable` nazywa zmienną do powiązania, `sign_in_command` polecenie do uruchomienia zamiast tego. | Powiąż sekret z `variable`, poproś człowieka o uruchomienie `sign_in_command` w terminalu albo użyj OpenCode. |
| `FAILED_PRECONDITION` + `WorkspaceChoice` | Wywołanie nie wskazuje przestrzeni roboczej, a token sięga kilku; `workspaces` je wymienia. | Wyślij `workspace`, jej id albo nazwę, w wywołaniu albo w kliencie. |
| `ALREADY_EXISTS` + `NameTaken` | Tę nazwę ma inny nieusunięty sandbox przestrzeni roboczej; `sandbox_id` to ten sandbox. | Użyj tego sandboxa albo wybierz inną nazwę. |

## Odmowy z samym kodem

| Kod | Co oznacza | Co zrobić |
| --- | --- | --- |
| `INVALID_ARGUMENT` | Pole jest błędne, a komunikat je nazywa i mówi, co przyjmuje; albo `request_id` przyszło ponownie z innymi polami. | Popraw pole. Nie ponawiaj bez zmian. |
| `NOT_FOUND` | Nie ma takiego sandboxa, szablonu, wolumenu ani sekretu albo token do niego nie sięga. Od serwera sandboxa: sandbox przeniósł się na inny. | Sprawdź id. SDK same łączą się ponownie, gdy sandbox się przeniósł. |
| `FAILED_PRECONDITION` | Stan nie pozwala na wywołanie, jak mówi komunikat: nowy rozmiar dla sandboxa PAUSED, sekret wciąż powiązany, wolumen wciąż zamontowany, szablon wciąż zapisywany, pulpit, który nie wystartował. | Najpierw zrób to, co mówi komunikat, a potem powtórz. |
| `ABORTED` | Ustawienia sandboxa zmieniły się, odkąd je odczytano (`if_revision`). | Odczytaj go ponownie i wprowadź zmianę jeszcze raz. |
| `RESOURCE_EXHAUSTED` | Bez `LimitReached`: sandbox obsługuje już 64 wywołań naraz albo wiadomość przekroczyła swój limit (1 MiB na żądanie, 17 MiB na `WriteFiles`). | Zakończ jakieś wywołanie albo poczekaj; duży plik przenieś przez link. |
| `UNAVAILABLE` | Bez szczegółu: żaden serwer teraz nie odpowiada albo sandbox przenosi się na inny serwer. | Powtórz za chwilę. |
| `PERMISSION_DENIED` | Token API nie ma dostępu do przestrzeni roboczej albo token zatwierdzony dla serwera MCP Agent Sandboxes wywołał inne API. Od serwera sandboxa: token dla innego serwera, po przeprowadzce. | Daj tokenowi dostęp do przestrzeni roboczej w Ustawieniach. SDK same łączą się ponownie po przeprowadzce. |
| `UNAUTHENTICATED` | Tokena brakuje, ma literówkę, wygasł albo został unieważniony. Od serwera sandboxa: token połączenia, który wygasł albo został unieważniony (`revoke_tokens`). | Sprawdź `PETHOST_TOKEN`. SDK same proszą o nowy token połączenia. |

Wywołanie środowiska uruchomieniowego odrzucone przez serwer sandboxa z `UNAUTHENTICATED`, `PERMISSION_DENIED` albo `NOT_FOUND` niczego nie zrobiło. SDK i CLI raz ponownie wywołują `ConnectSandbox` i je powtarzają; twój własny program przez HTTP robi to samo.

## Odpowiedzi, które mówią, że coś się nie udało

Niektóre wywołania się udają, a w odpowiedzi mówią, że część pracy się nie powiodła: wywołanie zrobiło, co mogło, a odpowiedź mówi, gdzie się zatrzymało.

| Odpowiedź | Wartości | Co zrobić |
| --- | --- | --- |
| `WriteFilesResponse.failure` | `NOT_FOUND`, `PERMISSION_DENIED`, `NOT_A_DIRECTORY`, `IS_A_DIRECTORY`, `NO_SPACE`, `EDIT_NOT_FOUND`, `EDIT_AMBIGUOUS` | Wykonano `done_count` zmian; popraw następną i wyślij resztę. |
| `ControlDesktopResponse.failure` | `OFF_SCREEN`, `UNKNOWN_KEY` | Wykonano `done_count` akcji; zrzut ekranu pokazuje ekran po nich. |
| `Command.state` | `TIMED_OUT`, `STOPPED`, `LOST` | `LOST`: sandbox stracił pamięć w trakcie działania polecenia; uruchom je ponownie. |
| `AgentTurn.state` | `FAILED`, `STOPPED`, `LOST` | `FAILED`: `failure_message` mówi dlaczego. `LOST`: wyślij prompt ponownie. |
| `Sandbox.state_reason` | `CRASH`, `UNPAID`, `IDLE`, `MAINTENANCE` | `CRASH`: `state_message` mówi dlaczego; uruchamia go tylko `ResumeSandbox`. |

Przez MCP `WriteFiles` albo `ControlDesktop`, które nie doszły do końca, są błędem narzędzia, z JSON-em takim, jakim odpowiada API.

## Na porcie, przy linku i przez SSH

| Odpowiedź | Co oznacza | Co zrobić |
| --- | --- | --- |
| 401 z portu | Port prywatny, a żądanie nie miało `Pethost-Token`, miało wygasły albo token innego portu. | Udostępnij port publicznie albo wyślij świeży token z `CreateLink`. |
| 503 „stopped: resume it” | Sandbox jest zatrzymany i nie budzi się na żądanie. SSH mówi te same słowa. | `ResumeSandbox` albo włącz `wake_when_stopped`. |
| 503 w trakcie przywracania | Jego dysk wraca z magazynu obiektów. | Poczekaj, a potem powtórz. |
| 403 od proxy ruchu wychodzącego | W sandboxie: jego lista ruchu wychodzącego nie dopuszcza hosta albo portu, a odpowiedź mówi, co odmówiło. | Dodaj host do `egress.allow`. |
| 421 Misdirected Request | W sandboxie: zwykłe żądanie HTTP do innego hosta niż ten, do którego otwarto połączenie. | Nic: klient otwiera nowe połączenie do tego hosta. |

## Bezpieczne ponawianie

Wywołanie, które coś tworzy, przyjmuje `request_id`: `CreateSandbox`, `ForkSandbox`, `CreateTemplate`, `CreateVolume`, `RunCommand` i `PromptAgent`. Wyślij to samo id ponownie po przekroczeniu czasu albo zgubionej odpowiedzi, a ponowienie odpowie tym, co zrobiło pierwsze wywołanie, przez 24 h. Pozostałe wywołania, które coś zmieniają, są idempotentne same w sobie: wstrzymanie wstrzymanego sandboxa albo usunięcie usuniętego odpowiada jego obecnym stanem. Jedno zastrzeżenie: sandbox trzyma id swoich poleceń i tur na dysku, więc taki, który stracił pamięć, mógł stracić te z ostatnich sekund, a ponowienie takiego polecenia uruchomi je jeszcze raz.

## Pytania

### Co znaczy „stopped: resume it”?

Sandbox jest zatrzymany, a jego cykl życia nie budzi go przy wywołaniu. `ResumeSandbox` go uruchamia, z plikami takimi, jakie zostawił.

### Dlaczego mój sandbox jest odrzucany z LimitReached?

Przestrzeń robocza osiągnęła limit swojego planu, który nazywa `limit`: zwykle `vcpus`, zajęte przez działające i wstrzymane sandboxy, albo okno startów, z `retry_time`.

### Czy ponawiać UNAVAILABLE?

Tak, po chwili. Z `NoCapacity` trochę później; z `Restoring`, gdy dysk wróci.

### Czy mogę parsować komunikat błędu?

Nie: rozgałęziaj po kodzie i typowanym szczególe. Komunikat to zdanie dla ludzi i może się zmienić.

[PoprzedniaLimity Pethost Agent Sandboxes](https://pethost.dev/pl/docs/sandboxes/limits/)

## Wypróbuj Pethost Agent Sandboxes

Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.

[Zacznij okres próbny](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Szablony](https://pethost.dev/pl/templates/)
- [O nas](https://pethost.dev/about/)
- [Dokumentacja](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/pl/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Regulamin](https://pethost.dev/terms/)
- [Prywatność](https://pethost.dev/privacy/)
- [Zwroty](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bazy danych

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

Agent Sandboxes

- [Sandboxy](https://pethost.dev/pl/sandboxes/)
- [Cennik](https://pethost.dev/pl/sandboxes/#pricing)
- [Dokumentacja](https://pethost.dev/pl/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Porównania

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/pl/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/pl/blog/coolify-cloud-vs-dokploy-cloud/)
- [Cennik Railway vs Render vs Fly.io](https://pethost.dev/pl/blog/railway-vs-render-vs-fly-io-pricing/)
- [Zarządzany hosting Docker Compose](https://pethost.dev/pl/blog/managed-docker-compose-hosting/)

Alternatywy

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