Документація Agent Sandboxes · Довідник
Помилки API пісочниць і що з ними робити
Що означає кожна відмова API і що робити далі, за її кодом і типізованою деталлю: для розгалужень програми й наступного кроку агента. Розгалужуйтеся за кодом і деталлю, ніколи не за повідомленням: це речення для людей, і воно може змінитися.
Як читати помилку в кожному SDK
Виклик, що не вдався, кидає виняток, відхиляє проміс або повертає помилку з кодом, повідомленням API і, якщо є, типізованою деталлю. Python кидає підклас SandboxesError на кожен код (AlreadyExistsError, FailedPreconditionError…) із деталлю в detail; TypeScript відхиляє з SandboxesError, у якого деталь — окреме поле (error.nameTaken); Go повертає *sandboxes.Error із полем на кожну деталь; Error у Rust має code() і details(). Тут уже зайнята назва дає скористатися пісочницею, що її має, а зупинена пісочниця продовжується:
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")
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);
});
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)
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_DENIED | API-токену не надано робочий простір, або токен, підтверджений для MCP-сервера Agent Sandboxes, викликав інший API. Від сервера пісочниці: токен для іншого сервера, після переїзду. | Надайте токену робочий простір у «Налаштуваннях». SDK самі підключаються знову після переїзду. |
UNAUTHENTICATED | Токена немає, його введено з помилкою, він сплив або відкликаний. Від сервера пісочниці: токен з’єднання сплив або відкликаний (revoke_tokens). | Перевірте PETHOST_TOKEN. Новий токен з’єднання SDK просять самі. |
Виклик середовища виконання, відхилений сервером пісочниці з UNAUTHENTICATED, PERMISSION_DENIED чи NOT_FOUND, нічого не зробив. SDK і CLI один раз знову звертаються до ConnectSandbox і повторюють його; ваша власна програма по HTTP робить так само.
Відповіді, що кажуть про невдачу
Деякі виклики вдаються й кажуть у відповіді, що частина роботи не вдалася: виклик зробив, що зміг, а відповідь каже, де він зупинився.
| Відповідь | Значення | Що робити |
|---|---|---|
WriteFilesResponse.failure | NOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUS | Внесено done_count змін; виправте наступну й надішліть решту. |
ControlDesktopResponse.failure | OFF_SCREEN, UNKNOWN_KEY | Виконано done_count дій; скриншот показує екран після них. |
Command.state | TIMED_OUT, STOPPED, LOST | LOST: пісочниця втратила пам’ять, поки команда працювала; запустіть її знову. |
AgentTurn.state | FAILED, STOPPED, LOST | FAILED: failure_message каже чому. LOST: дайте промпт знову. |
Sandbox.state_reason | CRASH, UNPAID, IDLE, MAINTENANCE | CRASH: 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 $ на місяць, який включає стільки ж використання.