Документация 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 | Вызов к остановленной песочнице, вход по 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
Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.