Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Referencja

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

Zaktualizowano · 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 oznaczaCo zrobić
FAILED_PRECONDITION + StoppedWywoł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 + RestoringJego 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 + LimitReachedLimit 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, _dayZa 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 + UsageUnpaidNic 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 + AgentSignInAgent 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 + WorkspaceChoiceWywoł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 + NameTakenTę 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

KodCo oznaczaCo zrobić
INVALID_ARGUMENTPole 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_FOUNDNie 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_PRECONDITIONStan 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.
ABORTEDUstawienia sandboxa zmieniły się, odkąd je odczytano (if_revision).Odczytaj go ponownie i wprowadź zmianę jeszcze raz.
RESOURCE_EXHAUSTEDBez 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.
UNAVAILABLEBez szczegółu: żaden serwer teraz nie odpowiada albo sandbox przenosi się na inny serwer.Powtórz za chwilę.
PERMISSION_DENIEDToken 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.
UNAUTHENTICATEDTokena 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ściCo zrobić
WriteFilesResponse.failureNOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUSWykonano done_count zmian; popraw następną i wyślij resztę.
ControlDesktopResponse.failureOFF_SCREEN, UNKNOWN_KEYWykonano done_count akcji; zrzut ekranu pokazuje ekran po nich.
Command.stateTIMED_OUT, STOPPED, LOSTLOST: sandbox stracił pamięć w trakcie działania polecenia; uruchom je ponownie.
AgentTurn.stateFAILED, STOPPED, LOSTFAILED: failure_message mówi dlaczego. LOST: wyślij prompt ponownie.
Sandbox.state_reasonCRASH, UNPAID, IDLE, MAINTENANCECRASH: 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 oznaczaCo zrobić
401 z portuPort 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 przywracaniaJego dysk wraca z magazynu obiektów.Poczekaj, a potem powtórz.
403 od proxy ruchu wychodzącegoW 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 RequestW 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ć.

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