---
title: "Erreurs de l’API des sandboxes, et que faire | Pethost Agent Sandboxes"
description: "Chaque refus de l’API des sandboxes, son code et son détail typé, ce qu’il veut dire et ce que votre programme ou votre agent doit faire ensuite."
---

[Documentation Agent Sandboxes](https://pethost.dev/fr/docs/sandboxes/) · Référence

# Erreurs de l’API des sandboxes, et que faire

Mis à jour le 22 novembre 2026 · 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é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.

[PrécédentLimites de Pethost Agent Sandboxes](https://pethost.dev/fr/docs/sandboxes/limits/)

## 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](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/fr/templates/)
- [À propos](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/fr/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Conditions](https://pethost.dev/terms/)
- [Confidentialité](https://pethost.dev/privacy/)
- [Remboursements](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de données

- [Postgres](https://pethost.dev/fr/postgres/)
- [Valkey](https://pethost.dev/fr/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/fr/sandboxes/)
- [Tarifs](https://pethost.dev/fr/sandboxes/#pricing)
- [Docs](https://pethost.dev/fr/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparatifs

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/fr/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/fr/blog/coolify-cloud-vs-dokploy-cloud/)
- [Tarifs Railway vs Render vs Fly.io](https://pethost.dev/fr/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hébergement Docker Compose managé](https://pethost.dev/fr/blog/managed-docker-compose-hosting/)

Alternatives

- [Alternatives à Railway](https://pethost.dev/fr/blog/railway-alternatives/)
- [Alternatives à Heroku](https://pethost.dev/fr/blog/heroku-alternatives/)
- [Alternatives à Dokploy](https://pethost.dev/fr/blog/dokploy-alternatives/)
- [Alternatives à Coolify](https://pethost.dev/fr/blog/coolify-alternatives/)
- [Alternatives à Render](https://pethost.dev/fr/blog/render-alternatives/)
- [Alternatives à Sliplane](https://pethost.dev/fr/blog/sliplane-alternatives/)
