---
title: "Помилки API пісочниць і що з ними робити | Pethost Agent Sandboxes"
description: "Кожна відмова API пісочниць, її код і типізована деталь, що вона означає і що далі робити вашій програмі чи агентові."
---

[Документація Agent Sandboxes](https://pethost.dev/uk/docs/sandboxes/) · Довідник

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

Оновлено 22 листопада 2026 р. · 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_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](https://pethost.dev/uk/docs/sandboxes/limits/)

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

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

[Почати пробний період](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Шаблони](https://pethost.dev/uk/templates/)
- [Про нас](https://pethost.dev/about/)
- [Документація](https://pethost.dev/docs/)
- [Блог](https://pethost.dev/uk/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Плагін](https://github.com/pethost-dev/plugin)
- [Умови](https://pethost.dev/terms/)
- [Конфіденційність](https://pethost.dev/privacy/)
- [Повернення коштів](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Бази даних

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

Agent Sandboxes

- [Пісочниці](https://pethost.dev/uk/sandboxes/)
- [Тарифи](https://pethost.dev/uk/sandboxes/#pricing)
- [Документація](https://pethost.dev/uk/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Порівняння

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/uk/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/uk/blog/coolify-cloud-vs-dokploy-cloud/)
- [Ціни Railway vs Render vs Fly.io](https://pethost.dev/uk/blog/railway-vs-render-vs-fly-io-pricing/)
- [Керований хостинг Docker Compose](https://pethost.dev/uk/blog/managed-docker-compose-hosting/)

Альтернативи

- [Альтернативи Railway](https://pethost.dev/uk/blog/railway-alternatives/)
- [Альтернативи Heroku](https://pethost.dev/uk/blog/heroku-alternatives/)
- [Альтернативи Dokploy](https://pethost.dev/uk/blog/dokploy-alternatives/)
- [Альтернативи Coolify](https://pethost.dev/uk/blog/coolify-alternatives/)
- [Альтернативи Render](https://pethost.dev/uk/blog/render-alternatives/)
- [Альтернативи Sliplane](https://pethost.dev/uk/blog/sliplane-alternatives/)
