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

[Документация Agent Sandboxes](https://pethost.dev/ru/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` | Вызов к остановленной песочнице, вход по 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` | Состояние не позволяет этот вызов, как он и говорит: новый размер для песочницы на паузе, секрет, который еще привязан, том, который еще подключен, шаблон, который еще сохраняется, рабочий стол, который не запустился. | Сначала сделайте то, что говорит сообщение, затем повторите. |
| `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 сами просят новый токен подключения. |

Вызов runtime, на который сервер песочницы ответил `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/ru/docs/sandboxes/limits/)

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

Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.

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

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Шаблоны](https://pethost.dev/ru/templates/)
- [О нас](https://pethost.dev/about/)
- [Документация](https://pethost.dev/docs/)
- [Блог](https://pethost.dev/ru/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/ru/postgres/)
- [Valkey](https://pethost.dev/ru/valkey/)

Agent Sandboxes

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

Сравнения

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

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

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