Documentation Agent Sandboxes · Référence
Erreurs de l’API des sandboxes, et que faire
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 :
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);
Refus avec un détail typé
| Code et détail | Ce qu’il veut dire | Que faire |
|---|---|---|
FAILED_PRECONDITION + Stopped | Un 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 + Restoring | Son 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 + NoCapacity | Aucun 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 + LimitReached | Une 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, _day | Trop 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 + UsageUnpaid | Rien 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 + AgentSignIn | Un 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 + WorkspaceChoice | L’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 + NameTaken | Une 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
| Code | Ce qu’il veut dire | Que faire |
|---|---|---|
INVALID_ARGUMENT | Un 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_FOUND | Pas 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_PRECONDITION | L’é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. |
ABORTED | Les paramètres de la sandbox ont changé depuis que vous les avez lus (if_revision). | Relisez-la, et refaites votre changement. |
RESOURCE_EXHAUSTED | Sans 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. |
UNAVAILABLE | Sans 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_DENIED | Le 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. |
UNAUTHENTICATED | Le 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éponse | Valeurs | Que faire |
|---|---|---|
WriteFilesResponse.failure | NOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUS | done_count changements ont été faits ; corrigez le suivant et envoyez le reste. |
ControlDesktopResponse.failure | OFF_SCREEN, UNKNOWN_KEY | done_count actions ont été faites ; la capture montre l’écran après elles. |
Command.state | TIMED_OUT, STOPPED, LOST | LOST : la sandbox a perdu sa mémoire pendant qu’elle tournait ; relancez-la. |
AgentTurn.state | FAILED, STOPPED, LOST | FAILED : failure_message dit pourquoi. LOST : redonnez le prompt. |
Sandbox.state_reason | CRASH, UNPAID, IDLE, MAINTENANCE | CRASH : 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éponse | Ce qu’elle veut dire | Que faire |
|---|---|---|
| 401 depuis un port | Un 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 restauration | Son disque revient du stockage objet. | Attendez, puis refaites l’appel. |
| 403 du proxy de sortie | Dans 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 Request | Dans 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.