Français
Menu de la documentation

Documentation Agent Sandboxes · Référence

Erreurs de l’API des sandboxes, et que faire

Mis à jour le · 7 min de lecture

Ce que veut dire chaque refus de l’API et que faire ensuite, selon son code et son détail typé : pour les branches d’un programme et la prochaine étape d’un agent. Décidez d’après le code et le détail, jamais d’après le message, qui est une phrase pour les personnes et peut changer.

Lire une erreur dans chaque SDK

Un appel qui échoue lève, rejette ou renvoie une erreur avec un code, le message de l’API et, s’il y en a un, un détail typé. Python lève une sous-classe de SandboxesError par code (AlreadyExistsError, FailedPreconditionError…) avec le détail dans detail ; TypeScript rejette avec une SandboxesError dont le détail est un champ à part (error.nameTaken) ; Go renvoie une *sandboxes.Error avec un champ par détail ; l’Error de Rust a code() et details(). Ici, un nom déjà pris réutilise la sandbox qui l’a, et une sandbox arrêtée est reprise :

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);

Refus avec un détail typé

Code et détailCe qu’il veut direQue faire
FAILED_PRECONDITION + StoppedUn appel vers une sandbox STOPPED, une connexion SSH ou une requête vers un port, et son cycle de vie ne dit pas wake_when_stopped.ResumeSandbox, puis refaites l’appel.
UNAVAILABLE + RestoringSon disque est rapatrié depuis le stockage objet pour son démarrage ; fetched_bytes sur total_bytes jusqu’ici, 10 s environ par GiB.Attendez, puis refaites l’appel.
UNAVAILABLE + NoCapacityAucun serveur n’a de place pour elle en ce moment ; bound dit ce qui manquait au dernier, et le fork_count d’une duplication combien de copies tiendraient.Réessayez plus tard, ou faites fork_count copies ou moins.
RESOURCE_EXHAUSTED + LimitReachedUne limite de l’offre, nommée par limit avec son max : vcpus, largest_size, volume_gib, template_versions, template_gib ou secrets.Supprimez ou arrêtez ce qui l’occupe, ou choisissez une offre plus grande. Les sandboxes actives et en pause occupent des vCPU.
RESOURCE_EXHAUSTED + LimitReached, starts_per_minute, _hour, _dayTrop de démarrages dans cette fenêtre glissante : créations, copies de duplications et démarrages de sandboxes arrêtées. Les démarrages sont gratuits et limités.Refaites l’appel à retry_time. Sans lui, l’appel demande plus que la fenêtre ne permet : découpez-le.
FAILED_PRECONDITION + UsageUnpaidRien ne paie pour l’espace de travail en ce moment : sa consommation incluse est épuisée et son solde est vide. Les sandboxes actives et en pause ont été arrêtées.Le propriétaire crédite le solde, ou démarre l’offre depuis l’essai gratuit, dans la console. La suspension se lève en quelques secondes.
FAILED_PRECONDITION + AgentSignInUn agent de code ne peut pas joindre son modèle : variable nomme la variable à lier, sign_in_command la commande à lancer à la place.Liez un secret à variable, faites lancer sign_in_command dans le terminal par une personne, ou utilisez OpenCode.
FAILED_PRECONDITION + WorkspaceChoiceL’appel ne nomme aucun espace de travail et le token en atteint plusieurs ; workspaces les liste.Envoyez workspace, son ID ou son nom, dans l’appel ou le client.
ALREADY_EXISTS + NameTakenUne autre sandbox non supprimée de l’espace de travail a ce nom ; sandbox_id est cette sandbox.Utilisez cette sandbox, ou choisissez un autre nom.

Refus par leur code seul

CodeCe qu’il veut direQue faire
INVALID_ARGUMENTUn champ est faux, et le message le nomme et dit ce qu’il accepte ; ou un request_id est revenu avec d’autres champs.Corrigez le champ. Ne réessayez pas tel quel.
NOT_FOUNDPas de sandbox, de template, de volume ou de secret de ce nom, ou aucun que le token atteint. Depuis le serveur d’une sandbox : la sandbox est passée sur un autre.Vérifiez l’ID. Les SDK se reconnectent seuls quand une sandbox a changé de serveur.
FAILED_PRECONDITIONL’état ne permet pas l’appel, comme le dit l’appel : une nouvelle taille pour une sandbox PAUSED, un secret encore lié, un volume encore monté, un template encore en cours d’enregistrement, un bureau qui n’a pas démarré.Faites d’abord ce que dit le message, puis refaites l’appel.
ABORTEDLes paramètres de la sandbox ont changé depuis que vous les avez lus (if_revision).Relisez-la, et refaites votre changement.
RESOURCE_EXHAUSTEDSans LimitReached : la sandbox sert déjà 64 appels en même temps, ou un message dépassait sa limite (1 MiB par requête, 17 MiB par WriteFiles).Terminez un appel ou attendez ; faites passer un gros fichier par un lien.
UNAVAILABLESans détail : aucun serveur ne répond en ce moment, ou la sandbox est en train de passer sur un autre serveur.Refaites l’appel dans un instant.
PERMISSION_DENIEDLe token d’API n’a pas reçu l’espace de travail, ou un token approuvé pour le serveur MCP d’Agent Sandboxes a appelé une autre API. Depuis le serveur d’une sandbox : un token pour un autre serveur, après un déplacement.Accordez l’espace de travail au token dans les Paramètres. Les SDK se reconnectent seuls après un déplacement.
UNAUTHENTICATEDLe token manque, est mal saisi, expiré ou révoqué. Depuis le serveur d’une sandbox : un token de connexion expiré ou révoqué (revoke_tokens).Vérifiez PETHOST_TOKEN. Les SDK demandent seuls un nouveau token de connexion.

Un appel au runtime refusé avec UNAUTHENTICATED, PERMISSION_DENIED ou NOT_FOUND par le serveur d’une sandbox n’a rien fait. Les SDK et la CLI redemandent une fois ConnectSandbox et le refont ; un programme à vous en HTTP fait de même.

Des réponses qui disent qu’une partie a échoué

Certains appels réussissent et disent dans leur réponse qu’une partie du travail a échoué : l’appel a fait ce qu’il pouvait, et la réponse dit où il s’est arrêté.

RéponseValeursQue faire
WriteFilesResponse.failureNOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUSdone_count changements ont été faits ; corrigez le suivant et envoyez le reste.
ControlDesktopResponse.failureOFF_SCREEN, UNKNOWN_KEYdone_count actions ont été faites ; la capture montre l’écran après elles.
Command.stateTIMED_OUT, STOPPED, LOSTLOST : la sandbox a perdu sa mémoire pendant qu’elle tournait ; relancez-la.
AgentTurn.stateFAILED, STOPPED, LOSTFAILED : failure_message dit pourquoi. LOST : redonnez le prompt.
Sandbox.state_reasonCRASH, UNPAID, IDLE, MAINTENANCECRASH : state_message dit pourquoi ; seul ResumeSandbox la démarre.

Par MCP, un WriteFiles ou un ControlDesktop arrêté en route est une erreur d’outil, avec son JSON tel que l’API le répond.

Sur un port, sur un lien et en SSH

RéponseCe qu’elle veut direQue faire
401 depuis un portUn port privé, et la requête n’avait pas de Pethost-Token, un token expiré ou celui d’un autre port.Rendez le port public, ou envoyez un token neuf de CreateLink.
503 « stopped: resume it »La sandbox est arrêtée et ne se réveille pas sur une requête. SSH dit les mêmes mots.ResumeSandbox, ou activez wake_when_stopped.
503 pendant la restaurationSon disque revient du stockage objet.Attendez, puis refaites l’appel.
403 du proxy de sortieDans la sandbox : son trafic sortant n’autorise pas l’hôte ou le port, et la réponse dit ce qui l’a refusé.Ajoutez l’hôte à egress.allow.
421 Misdirected RequestDans la sandbox : une requête HTTP en clair pour un autre hôte que celui pour lequel sa connexion a été ouverte.Rien : le client ouvre une nouvelle connexion pour cet hôte.

Réessayer sans risque

Un appel qui crée quelque chose prend un request_id : CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand et PromptAgent. Renvoyez le même ID après un délai dépassé ou une réponse perdue, et le nouvel essai répond ce qu’a fait le premier appel, pendant 24 heures. Les autres appels qui changent quelque chose sont idempotents tels quels : mettre en pause une sandbox en pause, supprimer une sandbox supprimée, répondent avec la sandbox telle qu’elle est. Une réserve : une sandbox garde sur son disque les ID de ses commandes et de ses tours, si bien qu’une sandbox qui a perdu sa mémoire a pu perdre ceux de ses dernières secondes, et un nouvel essai d’une telle commande la relance.

Questions

Que veut dire « stopped: resume it » ?

La sandbox est arrêtée et son cycle de vie ne la réveille pas à un appel. ResumeSandbox la démarre, ses fichiers tels qu’elle les a laissés.

Pourquoi ma sandbox est-elle refusée avec LimitReached ?

L’espace de travail a atteint une limite de son offre, que limit nomme : en général vcpus, occupés par les sandboxes actives et en pause, ou une fenêtre de démarrages, avec retry_time.

Faut-il réessayer après UNAVAILABLE ?

Oui, après un instant. Avec NoCapacity, un peu plus tard ; avec Restoring, une fois le disque revenu.

Puis-je analyser le message d’erreur ?

Non : décidez d’après le code et le détail typé. Le message est une phrase pour les personnes et peut changer.

Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

Démarrer l’essai gratuit