Русский
Меню документации

Документация 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Вызов к остановленной песочнице, вход по 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_DENIEDAPI-токену не выдан доступ к рабочему пространству, или токен, одобренный для MCP-сервера Agent Sandboxes, вызвал другой API. От сервера песочницы: токен для другого сервера после переезда.Выдайте токену доступ к рабочему пространству в настройках. После переезда SDK сами подключаются заново.
UNAUTHENTICATEDТокена нет, он написан с ошибкой, истек или отозван. От сервера песочницы: токен подключения истек или был отозван (revoke_tokens).Проверьте PETHOST_TOKEN. SDK сами просят новый токен подключения.

Вызов runtime, на который сервер песочницы ответил 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 $ в месяц, в который входит столько же использования.

Начать пробный период