Українська
Меню документації

Документація Agent Sandboxes · Довідник

Помилки API пісочниць і що з ними робити

Оновлено · 6 хв читання

Що означає кожна відмова API і що робити далі, за її кодом і типізованою деталлю: для розгалужень програми й наступного кроку агента. Розгалужуйтеся за кодом і деталлю, ніколи не за повідомленням: це речення для людей, і воно може змінитися.

Як читати помилку в кожному SDK

Виклик, що не вдався, кидає виняток, відхиляє проміс або повертає помилку з кодом, повідомленням API і, якщо є, типізованою деталлю. Python кидає підклас SandboxesError на кожен код (AlreadyExistsError, FailedPreconditionError…) із деталлю в detail; TypeScript відхиляє з SandboxesError, у якого деталь — окреме поле (error.nameTaken); Go повертає *sandboxes.Error із полем на кожну деталь; Error у Rust має code() і details(). Тут уже зайнята назва дає скористатися пісочницею, що її має, а зупинена пісочниця продовжується:

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

Відмови з типізованою деталлю

Код і детальЩо означаєЩо робити
FAILED_PRECONDITION + StoppedВиклик у пісочницю STOPPED, вхід по SSH чи запит до порту, а її життєвий цикл не каже wake_when_stopped.ResumeSandbox, потім повторіть виклик.
UNAVAILABLE + RestoringЇї диск повертається з об’єктного сховища для запуску; повернуто fetched_bytes із total_bytes, приблизно 10 с на GiB.Зачекайте, потім повторіть.
UNAVAILABLE + NoCapacityЗараз на жодному сервері немає для неї місця; bound каже, чого бракувало останньому, а fork_count під час копіювання — скільки копій вміщується.Спробуйте пізніше або зробіть fork_count копій чи менше.
RESOURCE_EXHAUSTED + LimitReachedЛіміт тарифу, названий у limit разом із max: vcpus, largest_size, volume_gib, template_versions, template_gib або secrets.Видаліть чи зупиніть те, що його займає, або виберіть більший тариф. vCPU займають пісочниці, що працюють і на паузі.
RESOURCE_EXHAUSTED + LimitReached, starts_per_minute, _hour, _dayЗабагато запусків у цьому ковзному вікні: створень, копій і запусків зупинених пісочниць. Запуски безкоштовні, але обмежені.Повторіть у момент retry_time. Якщо його немає, виклик просить більше, ніж дозволяє вікно: розбийте його.
FAILED_PRECONDITION + UsageUnpaidЗа робочий простір зараз нічим платити: включене використання вичерпано, а баланс порожній. Пісочниці, що працювали й були на паузі, зупинено.Власник поповнює баланс або починає тариф із пробного періоду в панелі. Обмеження знімається за лічені секунди.
FAILED_PRECONDITION + AgentSignInАгент для коду не може дістатися до своєї моделі: variable називає змінну, яку треба прив’язати, а sign_in_command — команду, яку можна виконати натомість.Прив’яжіть секрет до variable, попросіть людину виконати sign_in_command у терміналі або скористайтеся OpenCode.
FAILED_PRECONDITION + WorkspaceChoiceВиклик не називає робочого простору, а токен відкриває кілька; workspaces їх перелічує.Надсилайте workspace, його id чи назву, у виклику або клієнті.
ALREADY_EXISTS + NameTakenЦю назву має інша невидалена пісочниця робочого простору; sandbox_id — це вона.Скористайтеся тією пісочницею або виберіть іншу назву.

Відмови лише з кодом

КодЩо означаєЩо робити
INVALID_ARGUMENTПоле неправильне, і повідомлення його називає й каже, що воно приймає; або той самий request_id прийшов знову з іншими полями.Виправте поле. Не повторюйте як є.
NOT_FOUNDТакої пісочниці, шаблону, тому чи секрету немає, або токен до них не має доступу. Від сервера пісочниці: пісочниця переїхала на інший.Перевірте id. SDK самі підключаються знову, коли пісочниця переїхала.
FAILED_PRECONDITIONСтан не дозволяє виклику, як каже повідомлення: новий розмір для пісочниці PAUSED, секрет досі прив’язаний, том досі змонтований, шаблон досі зберігається, робочий стіл не запустився.Спершу зробіть те, що каже повідомлення, потім повторіть.
ABORTEDНалаштування пісочниці змінилися відтоді, як ви їх прочитали (if_revision).Прочитайте їх знову й повторіть свою зміну.
RESOURCE_EXHAUSTEDБез LimitReached: пісочниця вже обслуговує 64 виклики одночасно, або повідомлення перевищило свою межу (1 MiB на запит, 17 MiB на WriteFiles).Завершіть виклик або зачекайте; великий файл передавайте через посилання.
UNAVAILABLEБез деталі: зараз не відповідає жоден сервер, або пісочниця переїжджає на інший сервер.Повторіть за мить.
PERMISSION_DENIEDAPI-токену не надано робочий простір, або токен, підтверджений для MCP-сервера Agent Sandboxes, викликав інший API. Від сервера пісочниці: токен для іншого сервера, після переїзду.Надайте токену робочий простір у «Налаштуваннях». SDK самі підключаються знову після переїзду.
UNAUTHENTICATEDТокена немає, його введено з помилкою, він сплив або відкликаний. Від сервера пісочниці: токен з’єднання сплив або відкликаний (revoke_tokens).Перевірте PETHOST_TOKEN. Новий токен з’єднання SDK просять самі.

Виклик середовища виконання, відхилений сервером пісочниці з UNAUTHENTICATED, PERMISSION_DENIED чи NOT_FOUND, нічого не зробив. SDK і CLI один раз знову звертаються до ConnectSandbox і повторюють його; ваша власна програма по HTTP робить так само.

Відповіді, що кажуть про невдачу

Деякі виклики вдаються й кажуть у відповіді, що частина роботи не вдалася: виклик зробив, що зміг, а відповідь каже, де він зупинився.

ВідповідьЗначенняЩо робити
WriteFilesResponse.failureNOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUSВнесено done_count змін; виправте наступну й надішліть решту.
ControlDesktopResponse.failureOFF_SCREEN, UNKNOWN_KEYВиконано done_count дій; скриншот показує екран після них.
Command.stateTIMED_OUT, STOPPED, LOSTLOST: пісочниця втратила пам’ять, поки команда працювала; запустіть її знову.
AgentTurn.stateFAILED, STOPPED, LOSTFAILED: failure_message каже чому. LOST: дайте промпт знову.
Sandbox.state_reasonCRASH, UNPAID, IDLE, MAINTENANCECRASH: state_message каже чому; запускає її лише ResumeSandbox.

Через MCP WriteFiles чи ControlDesktop, що зупинився на півдорозі, — це помилка інструмента, з JSON таким, яким його відповідає API.

На порту, за посиланням і по SSH

ВідповідьЩо означаєЩо робити
401 від портуПриватний порт, а запит прийшов без Pethost-Token, із простроченим або з токеном іншого порту.Зробіть порт публічним або надішліть свіжий токен від CreateLink.
503 «stopped: resume it»Пісочниця зупинена й не прокидається від запиту. SSH каже те саме.ResumeSandbox або ввімкніть wake_when_stopped.
503 під час поверненняЇї диск повертається з об’єктного сховища.Зачекайте, потім повторіть.
403 від проксі вихідного трафікуУсередині пісочниці: її вихідний трафік не дозволяє хост чи порт, а відповідь каже, що саме відмовило.Додайте хост в egress.allow.
421 Misdirected RequestУсередині пісочниці: звичайний HTTP-запит до іншого хоста, ніж той, для якого відкрито з’єднання.Нічого: клієнт відкриє нове з’єднання для цього хоста.

Безпечні повтори

Виклик, що щось створює, приймає request_id: CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand і PromptAgent. Надішліть той самий id знову після тайм-ауту чи втраченої відповіді, і повтор відповість тим, що зробив перший виклик, протягом 24 год. Інші виклики, що щось змінюють, ідемпотентні самі по собі: пауза пісочниці на паузі чи видалення видаленої відповідають нею такою, як вона є. Одне застереження: пісочниця тримає id своїх команд і ходів на диску, тож та, що втратила пам’ять, могла втратити id своїх останніх секунд, і повтор такої команди виконає її знову.

Запитання

Що означає «stopped: resume it»?

Пісочниця зупинена, і її життєвий цикл не будить її від виклику. ResumeSandbox запускає її, з файлами такими, як вона їх лишила.

Чому мою пісочницю відхиляють із LimitReached?

Робочий простір досяг ліміту свого тарифу, який називає limit: зазвичай це vcpus, які займають пісочниці, що працюють і на паузі, або вікно запусків, із retry_time.

Чи варто повторювати UNAVAILABLE?

Так, за мить. З NoCapacity — трохи пізніше; з Restoring — щойно диск повернеться.

Чи можна розбирати текст повідомлення про помилку?

Ні: розгалужуйтеся за кодом і типізованою деталлю. Повідомлення — це речення для людей, і воно може змінитися.

Спробуйте Pethost Agent Sandboxes

Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.

Почати пробний період